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 53 51 4c 49 54 45 5f 4f 4b return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 hen the.** last
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 nt is finalized
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 finished. The
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 .** destructors
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 se | close] all
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 [BLOB handles],
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 bject. ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 deferred until
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 ite3] object is
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 destroyed while
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ter.** argument
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 3*);../*.** The
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 This is legacy
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 and deprecated.
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 It is included
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 * compatibility
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 ment,.** in the
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 ument. ^If the
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 t NULL, then it
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 * coming out of
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e L statements. ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 through to the
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 1st argument of
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 invocation. ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ored..**.** ^If
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 e skipped. ^If
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 c()] and passed
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 after the error
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20 exec() sets the
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 result. ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 obtained as if
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c lumn. ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 ULL pointer. ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 he 4th argument
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 nts the name of
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 ty string, or a
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 ust insure that
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 c().** is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 valid and open
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 ust not close [d
3e90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
3ea0: 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 on] specified by
3eb0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 .** the 1st
3ec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3ed0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 lite3_exec() whi
3ee0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 le sqlite3_exec(
3ef0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a ) is running..**
3f00: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
3f10: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d ation must not m
3f20: 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 odify the SQL st
3f30: 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 atement text pas
3f40: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 sed into.**
3f50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
3f60: 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 er of sqlite3_ex
3f70: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 ec() while sqlit
3f80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e e3_exec() is run
3f90: 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a ning..** </ul>.*
3fa0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 /.int sqlite3_ex
3fb0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ec(. sqlite3*,
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fe0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 /* An open data
3ff0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
4000: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 char *sql,
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4020: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
4030: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
4040: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 int (*callback)
4050: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
4060: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 *,char**), /* C
4070: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
4080: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 */. void *,
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40b0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 /* 1st argument
40c0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a to callback */.
40d0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 char **errmsg
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
4100: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
4110: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a n here */.);../*
4120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
4130: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 sult Codes.** KE
4140: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f YWORDS: SQLITE_O
4150: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b K {error code} {
4160: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 error codes}.**
4170: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c KEYWORDS: {resul
4180: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 t code} {result
4190: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e codes}.**.** Man
41a0: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f y SQLite functio
41b0: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 ns return an int
41c0: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 eger result code
41d0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 from the set sh
41e0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f own.** here in o
41f0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 rder to indicate
4200: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c success or fail
4210: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 ure..**.** New e
4220: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 rror codes may b
4230: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
4240: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
4250: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 Lite..**.** See
4260: 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
4270: 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e ERR_READ | exten
4280: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4290: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 ],.** [sqlite3_v
42a0: 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
42b0: 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 )] [SQLITE_ROLLB
42c0: 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 ACK | result cod
42d0: 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 es]..*/.#define
42e0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 SQLITE_OK
42f0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 0 /* Succe
4300: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a ssful result */.
4310: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d /* beginning-of-
4320: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 error-codes */.#
4330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 define SQLITE_ER
4340: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f ROR 1 /
4350: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d * SQL error or m
4360: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 issing database
4370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4380: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 E_INTERNAL 2
4390: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c /* Internal l
43a0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 ogic error in SQ
43b0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 Lite */.#define
43c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 SQLITE_PERM
43d0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 3 /* Acces
43e0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e s permission den
43f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
4400: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 QLITE_ABORT
4410: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 4 /* Callba
4420: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 ck routine reque
4430: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f sted an abort */
4440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4450: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 BUSY 5
4460: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
4470: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 file is locked
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4490: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 E_LOCKED 6
44a0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e /* A table in
44b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
44c0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 ne SQLITE_NOMEM
44e0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 7 /* A
44f0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 malloc() failed
4500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4510: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 E_READONLY 8
4520: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f /* Attempt to
4530: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c write a readonl
4540: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 y database */.#d
4550: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
4560: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a ERRUPT 9 /*
4570: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 Operation termi
4580: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 nated by sqlite3
4590: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 _interrupt()*/.#
45a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
45b0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f ERR 10 /
45c0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 * Some kind of d
45d0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 isk I/O error oc
45e0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e curred */.#defin
45f0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 e SQLITE_CORRUPT
4600: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 11 /* The
4610: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 database disk i
4620: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 mage is malforme
4630: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
4640: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 ITE_NOTFOUND
4650: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 12 /* Unknown
4660: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 opcode in sqlite
4670: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4690: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 TE_FULL 1
46a0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 3 /* Insertion
46b0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 failed because
46c0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c database is full
46d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
46e0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 TE_CANTOPEN 1
46f0: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 4 /* Unable to
4700: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 open the databa
4710: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
4720: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 ne SQLITE_PROTOC
4730: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 OL 15 /* Da
4740: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 tabase lock prot
4750: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 ocol error */.#d
4760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 efine SQLITE_EMP
4770: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a TY 16 /*
4780: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 Database is emp
4790: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ty */.#define SQ
47a0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 LITE_SCHEMA
47b0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 17 /* The dat
47c0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
47d0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nged */.#define
47e0: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 SQLITE_TOOBIG
47f0: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 18 /* Strin
4800: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 g or BLOB exceed
4810: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a s size limit */.
4820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
4830: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 ONSTRAINT 19
4840: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 /* Abort due to
4850: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
4860: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tion */.#define
4870: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 SQLITE_MISMATCH
4880: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 20 /* Data
4890: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f type mismatch */
48a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
48b0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 MISUSE 21
48c0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 /* Library used
48d0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a incorrectly */.
48e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
48f0: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 OLFS 22
4900: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 /* Uses OS featu
4910: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 res not supporte
4920: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 d on host */.#de
4930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 fine SQLITE_AUTH
4940: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
4950: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 Authorization de
4960: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nied */.#define
4970: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 SQLITE_FORMAT
4980: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 24 /* Auxil
4990: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f iary database fo
49a0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 rmat error */.#d
49b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e efine SQLITE_RAN
49c0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a GE 25 /*
49d0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 2nd parameter t
49e0: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f o sqlite3_bind o
49f0: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 ut of range */.#
4a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
4a10: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f TADB 26 /
4a20: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 * File opened th
4a30: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 at is not a data
4a40: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
4a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 fine SQLITE_NOTI
4a60: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 CE 27 /*
4a70: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 Notifications fr
4a80: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 om sqlite3_log()
4a90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4aa0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 TE_WARNING 2
4ab0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 8 /* Warnings
4ac0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 from sqlite3_log
4ad0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
4ae0: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 LITE_ROW
4af0: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 100 /* sqlite3
4b00: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 _step() has anot
4b10: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f her row ready */
4b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4b30: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 DONE 101
4b40: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
4b50: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 () has finished
4b60: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 executing */./*
4b70: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 end-of-error-cod
4b80: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 es */../*.** CAP
4b90: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 I3REF: Extended
4ba0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 Result Codes.**
4bb0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
4bc0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20 ded error code}
4bd0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
4be0: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 codes}.** KEYWOR
4bf0: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 DS: {extended re
4c00: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65 sult code} {exte
4c10: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4c20: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 s}.**.** In its
4c30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 default configur
4c40: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 ation, SQLite AP
4c50: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 I routines retur
4c60: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65 n one of 26 inte
4c70: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ger.** [SQLITE_O
4c80: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 K | result codes
4c90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
4ca0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
4cb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a n that many of.*
4cc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 * these result c
4cd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 odes are too coa
4ce0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
4cf0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
4d00: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
4d10: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
4d20: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
4d30: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
4d40: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
4d50: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
4d60: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
4d70: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
4d80: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 ersion 3.3.8 and
4d90: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a later) include.
4da0: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 ** support for a
4db0: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 dditional result
4dc0: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 codes that prov
4dd0: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 ide more detaile
4de0: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a d information.**
4df0: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 about errors. T
4e00: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 he extended resu
4e10: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61 lt codes are ena
4e20: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
4e30: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
4e40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4e50: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
4e60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
4e70: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
4e80: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a es()] API..**.**
4e90: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61 Some of the ava
4ea0: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20 ilable extended
4eb0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4ec0: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a listed here..**
4ed0: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20 One may expect
4ee0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 the number of ex
4ef0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4f00: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61 des will be expa
4f10: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e nd.** over time.
4f20: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
4f30: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65 uses extended re
4f40: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c sult codes shoul
4f50: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73 d expect.** to s
4f60: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f ee new result co
4f70: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65 des in future re
4f80: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
4f90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
4fa0: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64 TE_OK result cod
4fb0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20 e will never be
4fc0: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69 extended. It wi
4fd0: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 ll always.** be
4fe0: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f exactly zero..*/
4ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5000: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 IOERR_READ
5010: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5020: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a IOERR | (1<<8)).
5030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5040: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
5050: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5060: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 OERR | (2<<8)).#
5070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5080: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 ERR_WRITE
5090: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
50a0: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 ERR | (3<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
50c0: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 RR_FSYNC
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
50e0: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 RR | (4<<8)).#de
50f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5100: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 R_DIR_FSYNC
5110: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5120: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 R | (5<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5140: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 _TRUNCATE
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5160: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5180: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 FSTAT
5190: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
51a0: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (7<<8)).#defin
51b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 e SQLITE_IOERR_U
51c0: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 NLOCK
51d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
51e0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 SQLITE_IOERR_RD
5200: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
5220: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (9<<8)).#define
5230: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
5240: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 ETE (
5250: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5260: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 10<<8)).#define
5270: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
5280: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 CKED (
5290: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
52a0: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 11<<8)).#define
52b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d SQLITE_IOERR_NOM
52c0: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 EM (
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
52e0: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 12<<8)).#define
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 SQLITE_IOERR_ACC
5300: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 ESS (
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5320: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 13<<8)).#define
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 SQLITE_IOERR_CHE
5340: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 CKRESERVEDLOCK (
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5360: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 14<<8)).#define
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 SQLITE_IOERR_LOC
5380: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
53a0: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 15<<8)).#define
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f SQLITE_IOERR_CLO
53c0: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 SE (
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
53e0: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 16<<8)).#define
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 SQLITE_IOERR_DIR
5400: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 _CLOSE (
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5420: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 17<<8)).#define
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
5440: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 OPEN (
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5460: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 18<<8)).#define
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
5480: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 SIZE (
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
54a0: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 19<<8)).#define
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
54c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 LOCK (
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
54e0: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 20<<8)).#define
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d SQLITE_IOERR_SHM
5500: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 MAP (
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5520: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 21<<8)).#define
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 SQLITE_IOERR_SEE
5540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 K (
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5560: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 22<<8)).#define
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c SQLITE_IOERR_DEL
5580: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 ETE_NOENT (
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
55a0: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 23<<8)).#define
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 SQLITE_IOERR_MMA
55c0: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 P (
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
55e0: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 24<<8)).#define
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 SQLITE_IOERR_GET
5600: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 TEMPPATH (
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5620: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 25<<8)).#define
5630: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
5640: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 AREDCACHE (
5650: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 SQLITE_LOCKED |
5660: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 SQLITE_BUSY_REC
5680: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 OVERY
5690: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c (SQLITE_BUSY |
56a0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
56b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e e SQLITE_BUSY_SN
56c0: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 APSHOT
56d0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 (SQLITE_BUSY
56e0: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
56f0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
5700: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 EN_NOTEMPDIR
5710: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
5720: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 EN | (1<<8)).#de
5730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
5740: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 OPEN_ISDIR
5750: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
5760: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 OPEN | (2<<8)).#
5770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
5780: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 NTOPEN_FULLPATH
5790: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
57a0: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 NTOPEN | (3<<8))
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
57c0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 CORRUPT_VTAB
57d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
57e0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 CORRUPT | (1<<8)
57f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5800: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 _READONLY_RECOVE
5810: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 RY (SQLITE
5820: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c _READONLY | (1<<
5830: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5840: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 TE_READONLY_CANT
5850: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 LOCK (SQLI
5860: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 TE_READONLY | (2
5870: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5880: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f LITE_READONLY_RO
5890: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 LLBACK (SQ
58a0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
58b0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
58c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c SQLITE_ABORT_ROL
58d0: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 LBACK (
58e0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 SQLITE_ABORT | (
58f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5900: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5910: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 _CHECK (S
5920: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5930: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5940: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5950: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 AINT_COMMITHOOK
5960: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5970: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 AINT | (2<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5990: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e NSTRAINT_FOREIGN
59a0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f KEY (SQLITE_CO
59b0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 NSTRAINT | (3<<8
59c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
59d0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e E_CONSTRAINT_FUN
59e0: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 CTION (SQLIT
59f0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5a00: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5a10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5a20: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 _NOTNULL (S
5a30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5a40: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 | (5<<8)).#defi
5a50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
5a60: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 AINT_PRIMARYKEY
5a70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
5a80: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 AINT | (6<<8)).#
5a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
5aa0: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 NSTRAINT_TRIGGER
5ab0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
5ac0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 NSTRAINT | (7<<8
5ad0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5ae0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 E_CONSTRAINT_UNI
5af0: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 QUE (SQLIT
5b00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
5b10: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 8<<8)).#define S
5b20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5b30: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 _VTAB (S
5b40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
5b50: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 | (9<<8)).#defi
5b60: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
5b70: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 _RECOVER_WAL
5b80: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 (SQLITE_NOTICE
5b90: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
5bb0: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 _RECOVER_ROLLBAC
5bc0: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 K (SQLITE_NOTICE
5bd0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
5be0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
5bf0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 G_AUTOINDEX
5c00: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e (SQLITE_WARNIN
5c10: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a G | (1<<8))../*.
5c20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
5c30: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e gs For File Open
5c40: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a Operations.**.*
5c50: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
5c60: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
5c70: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
5c80: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
5c90: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
5ca0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
5cb0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
5cc0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
5cd0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
5ce0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
5cf0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 od..*/.#define S
5d00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
5d10: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
5d20: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 000001 /* Ok fo
5d30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5d40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5d50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
5d60: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
5d70: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 000002 /* Ok fo
5d80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5d90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5da0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
5db0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
5dc0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 000004 /* Ok fo
5dd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5de0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
5e00: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
5e10: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 000008 /* VFS o
5e20: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5e30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
5e40: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
5e50: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 000010 /* VFS o
5e60: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 QLITE_OPEN_AUTOP
5e80: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 ROXY 0x00
5e90: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 000020 /* VFS o
5ea0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5eb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 QLITE_OPEN_URI
5ec0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
5ed0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 000040 /* Ok fo
5ee0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5ef0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 QLITE_OPEN_MEMOR
5f10: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 Y 0x00
5f20: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 000080 /* Ok fo
5f30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
5f40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
5f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
5f60: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5f70: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 000100 /* VFS o
5f80: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5f90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
5fa0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
5fb0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 000200 /* VFS o
5fc0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
5fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
5fe0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
5ff0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 000400 /* VFS o
6000: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6010: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
6030: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 000800 /* VFS o
6040: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6050: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
6060: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
6070: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 001000 /* VFS o
6080: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6090: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
60a0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
60b0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 002000 /* VFS o
60c0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
60d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
60e0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
60f0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 004000 /* VFS o
6100: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
6110: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
6120: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
6130: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 008000 /* Ok fo
6140: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6150: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6160: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
6170: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
6180: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 010000 /* Ok fo
6190: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
61a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
61b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
61c0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 DCACHE 0x00
61d0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 020000 /* Ok fo
61e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
61f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
6210: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 TECACHE 0x00
6220: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 040000 /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 QLITE_OPEN_WAL
6260: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6270: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 080000 /* VFS o
6280: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 nly */../* Reser
6290: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 ved:
62a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
62b0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 0F00000 */../*.*
62c0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
62d0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
62e0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
62f0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
6300: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ics method of th
6310: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
6320: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
6330: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
6340: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
6350: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a ector of these.*
6360: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
6370: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
6380: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
6390: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
63a0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
63b0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
63c0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
63d0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
63e0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
63f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
6400: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
6410: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
6420: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
6430: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
6440: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6450: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
6460: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
6470: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
6480: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
6490: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
64a0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
64b0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
64c0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
64d0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
64e0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
64f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6500: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6510: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
6520: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
6530: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
6540: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
6550: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
6560: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
6570: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
6580: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
6590: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
65a0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
65b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
65c0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
65d0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
65e0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
65f0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
6600: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
6610: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
6620: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 ite(). The SQLI
6630: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
6640: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f FE_OVERWRITE pro
6650: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6660: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 .** after reboot
6670: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 following a cra
6680: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 sh or power loss
6690: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 , the only bytes
66a0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 in a.** file th
66b0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 at were written
66c0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
66d0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 on level might h
66e0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 ave changed.** a
66f0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 nd that adjacent
6700: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 bytes, even byt
6710: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
6720: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a me sector are.**
6730: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
6740: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a e unchanged..*/.
6750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6760: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 OCAP_ATOMIC
6770: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6780: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 000001.#define S
6790: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
67a0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 IC512
67b0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 0x00000002.#d
67c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
67d0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 AP_ATOMIC1K
67e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
67f0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0004.#define SQL
6800: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6810: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
6820: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 0x00000008.#def
6830: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6840: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 _ATOMIC4K
6850: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6860: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
6870: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b E_IOCAP_ATOMIC8K
6880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6890: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e x00000020.#defin
68a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
68b0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 TOMIC16K
68c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
68d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
68e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 IOCAP_ATOMIC32K
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6900: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 0000080.#define
6910: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6920: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 MIC64K
6930: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 0x00000100.#
6940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6950: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
6960: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6970: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00200.#define SQ
6980: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
6990: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 NTIAL
69a0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 0x00000400.#de
69b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
69c0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 P_UNDELETABLE_WH
69d0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 EN_OPEN 0x00000
69e0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 800.#define SQLI
69f0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
6a00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
6a10: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 0x00001000../*.*
6a20: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 * CAPI3REF: File
6a30: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a Locking Levels.
6a40: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 **.** SQLite use
6a50: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 s one of these i
6a60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
6a70: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 the second.** a
6a80: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 rgument to calls
6a90: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 it makes to the
6aa0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
6ab0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a lock() methods.*
6ac0: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 * of an [sqlite3
6ad0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
6ae0: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ect..*/.#define
6af0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
6b00: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 0.#def
6b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
6b20: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a SHARED 1.
6b30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
6b40: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 OCK_RESERVED
6b50: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
6b60: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 TE_LOCK_PENDING
6b70: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
6b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
6b90: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a USIVE 4../*.
6ba0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e ** CAPI3REF: Syn
6bb0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 chronization Typ
6bc0: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 e Flags.**.** Wh
6bd0: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 en SQLite invoke
6be0: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 s the xSync() me
6bf0: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 thod of an.** [s
6c00: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
6c10: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 s] object it use
6c20: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 s a combination
6c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 of.** these inte
6c40: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 ger values as th
6c50: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
6c60: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 t..**.** When th
6c70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
6c80: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 TAONLY flag is u
6c90: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 sed, it means th
6ca0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f at the.** sync o
6cb0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 peration only ne
6cc0: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 eds to flush dat
6cd0: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 a to mass storag
6ce0: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 e. Inode.** inf
6cf0: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f ormation need no
6d00: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 t be flushed. If
6d10: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
6d20: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 bits of the flag
6d30: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 .** equal SQLITE
6d40: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 _SYNC_NORMAL, th
6d50: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 at means to use
6d60: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 normal fsync() s
6d70: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 emantics..** If
6d80: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
6d90: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 its equal SQLITE
6da0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 _SYNC_FULL, that
6db0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 means.** to use
6dc0: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 Mac OS X style
6dd0: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 fullsync instead
6de0: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a of fsync()..**.
6df0: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 ** Do not confus
6e00: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e e the SQLITE_SYN
6e10: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
6e20: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
6e30: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ags.** with the
6e40: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
6e50: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 ous]=NORMAL and
6e60: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
6e70: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 ous]=FULL.** set
6e80: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e tings. The [syn
6e90: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d chronous pragma]
6ea0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e determines when
6eb0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a calls to the.**
6ec0: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f xSync VFS metho
6ed0: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c d occur and appl
6ee0: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 ies uniformly ac
6ef0: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 ross all platfor
6f00: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 ms..** The SQLIT
6f10: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e E_SYNC_NORMAL an
6f20: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 d SQLITE_SYNC_FU
6f30: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 LL flags determi
6f40: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 ne how.** energe
6f50: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 tic or rigorous
6f60: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 or forceful the
6f70: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 sync operations
6f80: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 are and.** only
6f90: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 make a differenc
6fa0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 e on Mac OSX for
6fb0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c the default SQL
6fc0: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 ite code..** (Th
6fd0: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d ird-party VFS im
6fe0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 plementations mi
6ff0: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 ght also make th
7000: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a e distinction.**
7010: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f between SQLITE_
7020: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7030: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7040: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a , but among the.
7050: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 ** operating sys
7060: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 tems natively su
7070: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
7080: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a e, only Mac OSX.
7090: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 ** cares about t
70a0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a he difference.).
70b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
70c0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 E_SYNC_NORMAL
70d0: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 0x00002.#de
70e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
70f0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 _FULL 0
7100: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 x00003.#define S
7110: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f QLITE_SYNC_DATAO
7120: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 NLY 0x00010
7130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
7140: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f : OS Interface O
7150: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a pen File Handle.
7160: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 **.** An [sqlite
7170: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 3_file] object r
7180: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 epresents an ope
7190: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a n file in the .*
71a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c * [sqlite3_vfs |
71b0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
71c0: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 yer]. Individua
71d0: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a l OS interface.*
71e0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
71f0: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 s will.** want t
7200: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 o subclass this
7210: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 object by append
7220: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ing additional f
7230: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ields.** for the
7240: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 ir own use. The
7250: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 pMethods entry
7260: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
7270: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
7280: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
7290: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d t that defines m
72a0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f ethods for perfo
72b0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 rming.** I/O ope
72c0: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f rations on the o
72d0: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 pen file..*/.typ
72e0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
72f0: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 te3_file sqlite3
7300: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 _file;.struct sq
7310: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 lite3_file {. c
7320: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 onst struct sqli
7330: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a te3_io_methods *
7340: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 pMethods; /* Me
7350: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 thods for an ope
7360: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a n file */.};../*
7370: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
7380: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 Interface File
7390: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 Virtual Methods
73a0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 Object.**.** Eve
73b0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 ry file opened b
73c0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 y the [sqlite3_v
73d0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
73e0: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a populates an.**
73f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
7400: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 object (or, more
7410: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 commonly, a sub
7420: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 class of the.**
7430: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
7440: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f bject) with a po
7450: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
7460: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
7470: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a ect..** This obj
7480: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
7490: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 methods used to
74a0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
74b0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 operations.** ag
74c0: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 ainst the open f
74d0: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 ile represented
74e0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
74f0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a file] object..**
7500: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 .** If the [sqli
7510: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d te3_vfs.xOpen] m
7520: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 ethod sets the s
7530: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
7540: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a hods element .**
7550: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 to a non-NULL p
7560: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 ointer, then the
7570: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
7580: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f ods.xClose metho
7590: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f d.** may be invo
75a0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 ked even if the
75b0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
75c0: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 en] reported tha
75d0: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 t it failed. Th
75e0: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f e.** only way to
75f0: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 prevent a call
7600: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 to xClose follow
7610: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 ing a failed [sq
7620: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7630: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b .** is for the [
7640: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
7650: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 n] to set the sq
7660: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
7670: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 ods element.** t
7680: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 o NULL..**.** Th
7690: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
76a0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 to xSync may be
76b0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
76c0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a SYNC_NORMAL] or.
76d0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f ** [SQLITE_SYNC_
76e0: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 FULL]. The firs
76f0: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 t choice is the
7700: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a normal fsync()..
7710: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 ** The second ch
7720: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 oice is a Mac OS
7730: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e X style fullsyn
7740: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f c. The [SQLITE_
7750: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a SYNC_DATAONLY].*
7760: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 * flag may be OR
7770: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 ed in to indicat
7780: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 e that only the
7790: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 data of the file
77a0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 .** and not its
77b0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 inode needs to b
77c0: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 e synced..**.**
77d0: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 The integer valu
77e0: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e es to xLock() an
77f0: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 d xUnlock() are
7800: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a one of.** <ul>.*
7810: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c * <li> [SQLITE_L
7820: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c OCK_NONE],.** <l
7830: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
7840: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e SHARED],.** <li>
7850: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 [SQLITE_LOCK_RE
7860: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e SERVED],.** <li>
7870: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 [SQLITE_LOCK_PE
7880: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c NDING], or.** <l
7890: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
78a0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c EXCLUSIVE]..** <
78b0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 /ul>.** xLock()
78c0: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f increases the lo
78d0: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 ck. xUnlock() de
78e0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
78f0: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 ..** The xCheckR
7900: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 eservedLock() me
7910: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 thod checks whet
7920: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 her any database
7930: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 connection,.**
7940: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 either in this p
7950: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d rocess or in som
7960: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c e other process,
7970: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 is holding a RE
7980: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 SERVED,.** PENDI
7990: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 NG, or EXCLUSIVE
79a0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c lock on the fil
79b0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 e. It returns t
79c0: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 rue.** if such a
79d0: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 lock exists and
79e0: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 false otherwise
79f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c ..**.** The xFil
7a00: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f eControl() metho
7a10: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 d is a generic i
7a20: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c nterface that al
7a30: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 lows custom.** V
7a40: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
7a50: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 ns to directly c
7a60: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 ontrol an open f
7a70: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a ile using the.**
7a80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
7a90: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 ontrol()] interf
7aa0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 ace. The second
7ab0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 "op" argument i
7ac0: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 s an.** integer
7ad0: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 opcode. The thi
7ae0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 rd argument is a
7af0: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 generic pointer
7b00: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 intended to.**
7b10: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 point to a struc
7b20: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f ture that may co
7b30: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 ntain arguments
7b40: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 or space in whic
7b50: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 h to.** write re
7b60: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f turn values. Po
7b70: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 tential uses for
7b80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 xFileControl()
7b90: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 might be.** func
7ba0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 tions to enable
7bb0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 blocking locks w
7bc0: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f ith timeouts, to
7bd0: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c change the.** l
7be0: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 ocking strategy
7bf0: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 (for example to
7c00: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 use dot-file loc
7c10: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a ks), to inquire.
7c20: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 ** about the sta
7c30: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f tus of a lock, o
7c40: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 r to break stale
7c50: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c locks. The SQL
7c60: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 ite.** core rese
7c70: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 rves all opcodes
7c80: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 less than 100 f
7c90: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a or its own use..
7ca0: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e ** A [SQLITE_FCN
7cb0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c TL_LOCKSTATE | l
7cc0: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 ist of opcodes]
7cd0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 less than 100 is
7ce0: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 available..** A
7cf0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
7d00: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d define a custom
7d10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
7d20: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 thod should use
7d30: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 opcodes.** great
7d40: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 er than 100 to a
7d50: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 void conflicts.
7d60: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
7d70: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 ions should.** r
7d80: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f eturn [SQLITE_NO
7d90: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 TFOUND] for file
7da0: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 control opcodes
7db0: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
7dc0: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a t.** recognize..
7dd0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f **.** The xSecto
7de0: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 rSize() method r
7df0: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f eturns the secto
7e00: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a r size of the.**
7e10: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 device that und
7e20: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e erlies the file.
7e30: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a The sector siz
7e40: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 e is the.** mini
7e50: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 mum write that c
7e60: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 an be performed
7e70: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 without disturbi
7e80: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 ng.** other byte
7e90: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 s in the file.
7ea0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
7eb0: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 cteristics().**
7ec0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 method returns a
7ed0: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 bit vector desc
7ee0: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 ribing behaviors
7ef0: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 of the.** under
7f00: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a lying device:.**
7f10: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
7f20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
7f30: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b TOMIC].** <li> [
7f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7f50: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC512].** <li>
7f60: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7f70: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC1K].** <li>
7f80: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7f90: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC2K].** <li>
7fa0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7fb0: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC4K].** <li>
7fc0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7fd0: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 OMIC8K].** <li>
7fe0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7ff0: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC16K].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC32K].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c ATOMIC64K].** <l
8040: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
8050: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a _SAFE_APPEND].**
8060: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8070: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a CAP_SEQUENTIAL].
8080: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
8090: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
80a0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 ATOMIC property
80b0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 means that all w
80c0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 rites of.** any
80d0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e size are atomic.
80e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
80f0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c AP_ATOMICnnn val
8100: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 ues.** mean that
8110: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b writes of block
8120: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 s that are nnn b
8130: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 ytes in size and
8140: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 .** are aligned
8150: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 to an address wh
8160: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ich is an intege
8170: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a r multiple of.**
8180: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e nnn are atomic.
8190: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
81a0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 AP_SAFE_APPEND v
81b0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 alue means.** th
81c0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 at when data is
81d0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 appended to a fi
81e0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 le, the data is
81f0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 appended.** firs
8200: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 t then the size
8210: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 of the file is e
8220: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 xtended, never t
8230: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 he other.** way
8240: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c around. The SQL
8250: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
8260: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 TIAL property me
8270: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f ans that.** info
8280: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 rmation is writt
8290: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 en to disk in th
82a0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 e same order as
82b0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 calls.** to xWri
82c0: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 te()..**.** If x
82d0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 Read() returns S
82e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 QLITE_IOERR_SHOR
82f0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 T_READ it must a
8300: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 lso fill.** in t
8310: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f he unread portio
8320: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ns of the buffer
8330: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 with zeros. A
8340: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c VFS that.** fail
8350: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 s to zero-fill s
8360: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 hort reads might
8370: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 seem to work.
8380: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c However,.** fail
8390: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c ure to zero-fill
83a0: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c short reads wil
83b0: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 l eventually lea
83c0: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 d to.** database
83d0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
83e0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
83f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
8400: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 s sqlite3_io_met
8410: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c hods;.struct sql
8420: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
8430: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e {. int iVersion
8440: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 ;. int (*xClose
8450: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 )(sqlite3_file*)
8460: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 ;. int (*xRead)
8470: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8480: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c void*, int iAmt,
8490: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 sqlite3_int64 i
84a0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Ofst);. int (*x
84b0: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 Write)(sqlite3_f
84c0: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ile*, const void
84d0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c *, int iAmt, sql
84e0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 ite3_int64 iOfst
84f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e );. int (*xTrun
8500: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 cate)(sqlite3_fi
8510: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
8520: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 64 size);. int
8530: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 (*xSync)(sqlite3
8540: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 _file*, int flag
8550: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c s);. int (*xFil
8560: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 eSize)(sqlite3_f
8570: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8580: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 t64 *pSize);. i
8590: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 nt (*xLock)(sqli
85a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b te3_file*, int);
85b0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b . int (*xUnlock
85c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
85d0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
85e0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 CheckReservedLoc
85f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
8600: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b , int *pResOut);
8610: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f . int (*xFileCo
8620: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 ntrol)(sqlite3_f
8630: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f ile*, int op, vo
8640: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 id *pArg);. int
8650: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 (*xSectorSize)(
8660: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
8670: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 int (*xDeviceC
8680: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 haracteristics)(
8690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
86a0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f /* Methods abo
86b0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 ve are valid for
86c0: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 version 1 */.
86d0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 int (*xShmMap)(s
86e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
86f0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c t iPg, int pgsz,
8700: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 int, void volat
8710: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a ile**);. int (*
8720: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 xShmLock)(sqlite
8730: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 3_file*, int off
8740: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 set, int n, int
8750: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 flags);. void (
8760: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 *xShmBarrier)(sq
8770: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8780: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 int (*xShmUnmap)
8790: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
87a0: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b int deleteFlag);
87b0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
87c0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
87d0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 r version 2 */.
87e0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 int (*xFetch)(s
87f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
8800: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
8810: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 t, int iAmt, voi
8820: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 d **pp);. int (
8830: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 *xUnfetch)(sqlit
8840: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
8850: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 3_int64 iOfst, v
8860: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 oid *p);. /* Me
8870: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
8880: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
8890: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 n 3 */. /* Addi
88a0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d tional methods m
88b0: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
88c0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a uture releases *
88d0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
88e0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 3REF: Standard F
88f0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f ile Control Opco
8900: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 des.**.** These
8910: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
8920: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
8930: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
8940: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
8950: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
8960: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
8970: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
8980: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
8990: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
89a0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 e..**.** The [SQ
89b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
89c0: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 TATE] opcode is
89d0: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 used for debuggi
89e0: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ng. This.** opc
89f0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 ode causes the x
8a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
8a10: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 od to write the
8a20: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 current state of
8a30: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e .** the lock (on
8a40: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 e of [SQLITE_LOC
8a50: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 K_NONE], [SQLITE
8a60: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a _LOCK_SHARED],.*
8a70: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 * [SQLITE_LOCK_R
8a80: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 ESERVED], [SQLIT
8a90: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
8aa0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b or [SQLITE_LOCK
8ab0: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 _EXCLUSIVE]).**
8ac0: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 into an integer
8ad0: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 that the pArg ar
8ae0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f gument points to
8af0: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 . This capabilit
8b00: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 y.** is used dur
8b10: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 ing testing and
8b20: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 only needs to be
8b30: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 supported when
8b40: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 SQLITE_TEST.** i
8b50: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 s defined..** <u
8b60: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 l>.** <li>[[SQLI
8b70: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
8b80: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NT]].** The [SQL
8b90: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
8ba0: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 INT] opcode is u
8bb0: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f sed by SQLite to
8bc0: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a give the VFS.**
8bd0: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 layer a hint of
8be0: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 how large the d
8bf0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c atabase file wil
8c00: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 l grow to be dur
8c10: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 ing the.** curre
8c20: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 nt transaction.
8c30: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f This hint is no
8c40: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 t guaranteed to
8c50: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 be accurate but
8c60: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 it.** is often c
8c70: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 lose. The under
8c80: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 lying VFS might
8c90: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c choose to preall
8ca0: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a ocate database.*
8cb0: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 * file space bas
8cc0: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 ed on this hint
8cd0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 in order to help
8ce0: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 writes to the d
8cf0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
8d00: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a run faster..**.*
8d10: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
8d20: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
8d30: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
8d40: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
8d50: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
8d60: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 d to request tha
8d70: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 t the VFS.** ext
8d80: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 ends and truncat
8d90: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
8da0: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f file in chunks o
8db0: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 f a size specifi
8dc0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 ed.** by the use
8dd0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 r. The fourth ar
8de0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
8df0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
8e00: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f )] should .** po
8e10: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 int to an intege
8e20: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e r (type int) con
8e30: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 taining the new
8e40: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 chunk-size to us
8e50: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d e.** for the nom
8e60: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e inated database.
8e70: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 Allocating data
8e80: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 base file space
8e90: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e in large.** chun
8ea0: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 ks (say 1MB at a
8eb0: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 time), may redu
8ec0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 ce file-system f
8ed0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 ragmentation and
8ee0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 .** improve perf
8ef0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 ormance on some
8f00: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c systems..**.** <
8f10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
8f20: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d L_FILE_POINTER]]
8f30: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
8f40: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
8f50: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ER] opcode is us
8f60: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 ed to obtain a p
8f70: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ointer.** to the
8f80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
8f90: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 object associate
8fa0: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 d with a particu
8fb0: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 lar database.**
8fc0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 connection. See
8fd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
8fe0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f le_control()] do
8ff0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a cumentation for.
9000: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
9010: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
9020: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9030: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
9040: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c ]].** ^(The [SQL
9050: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
9060: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 MITTED] opcode i
9070: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 s generated inte
9080: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c rnally by.** SQL
9090: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 ite and sent to
90a0: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 all VFSes in pla
90b0: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 ce of a call to
90c0: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 the xSync method
90d0: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 .** when the dat
90e0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
90f0: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e has [PRAGMA syn
9100: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f chronous] set to
9110: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 OFF.)^.** Some
9120: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
9130: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e s need this sign
9140: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f al in order to o
9150: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 perate correctly
9160: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 .** when [PRAGMA
9170: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 synchronous | P
9180: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
9190: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 s=OFF] is set, b
91a0: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 ut most .** VFSe
91b0: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 s do not need th
91c0: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 is signal and sh
91d0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 ould silently ig
91e0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 nore this opcode
91f0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
9200: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c s should not cal
9210: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f l [sqlite3_file_
9220: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 control()] with
9230: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 this.** opcode a
9240: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 s doing so may d
9250: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 isrupt the opera
9260: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
9270: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a ialized VFSes.**
9280: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 that do require
9290: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 it. .**.** <li
92a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
92b0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d WIN32_AV_RETRY]]
92c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
92d0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
92e0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
92f0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
9300: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
9310: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
9320: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
9330: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
9340: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
9350: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
9360: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
9370: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 provide robustne
9380: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e ss in the presen
9390: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 ce of.** anti-vi
93a0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 rus programs. B
93b0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 y default, the w
93c0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 indows VFS will
93d0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c retry file read,
93e0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 .** file write,
93f0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 and file delete
9400: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f operations up to
9410: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 10 times, with
9420: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 a delay.** of 25
9430: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 milliseconds be
9440: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 fore the first r
9450: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 etry and with th
9460: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 e delay increasi
9470: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 ng.** by an addi
9480: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 tional 25 millis
9490: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 econds with each
94a0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 subsequent retr
94b0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f y. This.** opco
94c0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 de allows these
94d0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 two values (10 r
94e0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 etries and 25 mi
94f0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 lliseconds of de
9500: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 lay).** to be ad
9510: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c justed. The val
9520: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 ues are changed
9530: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 for all database
9540: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
9550: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
9560: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 process. The ar
9570: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
9580: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
9590: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 of two.** intege
95a0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 rs where the fir
95b0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 st integer i the
95c0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 new retry count
95d0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a and the second.
95e0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 ** integer is th
95f0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 e delay. If eit
9600: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e her integer is n
9610: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
9620: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 e setting.** is
9630: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 not changed but
9640: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f instead the prio
9650: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 r value of that
9660: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 setting is writt
9670: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 en.** into the a
9680: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f rray entry, allo
9690: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 wing the current
96a0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 retry settings
96b0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f to be.** interro
96c0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e gated. The zDbN
96d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
96e0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
96f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9700: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d TL_PERSIST_WAL]]
9710: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
9720: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 _FCNTL_PERSIST_W
9730: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 AL] opcode is us
9740: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
9750: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
9760: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 tent [WAL | Writ
9770: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 e Ahead Log] set
9780: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c ting. By defaul
9790: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 t, the auxiliary
97a0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 .** write ahead
97b0: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d log and shared m
97c0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 emory files used
97d0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e for transaction
97e0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 control.** are
97f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
9800: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c leted when the l
9810: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e atest connection
9820: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
9830: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 .** closes. Set
9840: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 ting persistent
9850: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 WAL mode causes
9860: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 those files to p
9870: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 ersist after.**
9880: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 close. Persisti
9890: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 ng the files is
98a0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 useful when othe
98b0: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 r processes that
98c0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 do not.** have
98d0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e write permission
98e0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 on the director
98f0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 y containing the
9900: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
9910: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 ant.** to read t
9920: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9930: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 , as the WAL and
9940: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
9950: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a iles must exist.
9960: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 ** in order for
9970: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 the database to
9980: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 be readable. Th
9990: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
99a0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
99b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
99c0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 ] for this opcod
99d0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f e should be a po
99e0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
99f0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 ger..** That int
9a00: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 eger is 0 to dis
9a10: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 able persistent
9a20: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f WAL mode or 1 to
9a30: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 enable persiste
9a40: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 nt.** WAL mode.
9a50: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
9a60: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
9a70: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
9a80: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
9a90: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 * WAL persistenc
9aa0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
9ab0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9ac0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 NTL_POWERSAFE_OV
9ad0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
9ae0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9af0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
9b00: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ITE] opcode is u
9b10: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
9b20: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
9b30: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 stent "powersafe
9b40: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 -overwrite" or "
9b50: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 PSOW" setting.
9b60: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 The PSOW setting
9b70: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 .** determines t
9b80: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 he [SQLITE_IOCAP
9b90: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
9ba0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 RITE] bit of the
9bb0: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 .** xDeviceChara
9bc0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
9bd0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ds. The fourth p
9be0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
9bf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
9c00: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
9c10: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
9c20: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
9c30: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
9c40: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
9c50: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d to disable zero-
9c60: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 damage mode or 1
9c70: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d to enable zero-
9c80: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 damage.** mode.
9c90: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
9ca0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
9cb0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
9cc0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
9cd0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f * zero-damage mo
9ce0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a de setting..**.*
9cf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9d00: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d CNTL_OVERWRITE]]
9d10: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
9d20: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
9d30: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f ] opcode is invo
9d40: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 ked by SQLite af
9d50: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 ter opening.** a
9d60: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 write transacti
9d70: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 on to indicate t
9d80: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 hat, unless it i
9d90: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f s rolled back fo
9da0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e r some.** reason
9db0: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 , the entire dat
9dc0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
9dd0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 be overwritten b
9de0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a y the current .*
9df0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 * transaction. T
9e00: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 his is used by V
9e10: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 ACUUM operations
9e20: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
9e30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
9e40: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ME]].** ^The [SQ
9e50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
9e60: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 ME] opcode can b
9e70: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
9e80: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a the names of.**
9e90: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 all [VFSes] in
9ea0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 the VFS stack.
9eb0: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 The names are of
9ec0: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 all VFS shims a
9ed0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 nd the.** final
9ee0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 bottom-level VFS
9ef0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 are written int
9f00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
9f10: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
9f20: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
9f30: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 d the result is
9f40: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 stored in the ch
9f50: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 ar* variable.**
9f60: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 that the fourth
9f70: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 parameter of [sq
9f80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9f90: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e ol()] points to.
9fa0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 .** The caller i
9fb0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
9fc0: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 r freeing the me
9fd0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 mory when done.
9fe0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 As with.** all
9ff0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 file-control act
a000: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e ions, there is n
a010: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 o guarantee that
a020: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 this will actua
a030: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 lly.** do anythi
a040: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f ng. Callers sho
a050: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 uld initialize t
a060: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a070: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 e to a NULL.** p
a080: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 ointer in case t
a090: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
a0a0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e is not implemen
a0b0: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d ted. This file-
a0c0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e control.** is in
a0d0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e tended for diagn
a0e0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a ostic use only..
a0f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a100: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
a110: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 ].** ^Whenever a
a120: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
a130: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 ent is parsed, a
a140: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f n [SQLITE_FCNTL_
a150: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 PRAGMA] .** file
a160: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 control is sent
a170: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 to the open [sq
a180: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
a190: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ct corresponding
a1a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 .** to the datab
a1b0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 ase file to whic
a1c0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 h the pragma sta
a1d0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e tement refers. ^
a1e0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
a1f0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 to the [SQLITE_F
a200: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
a210: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 e control is an
a220: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e array of.** poin
a230: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
a240: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 (char**) in whic
a250: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 h the second ele
a260: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 ment of the arra
a270: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 y.** is the name
a280: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 of the pragma a
a290: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 nd the third ele
a2a0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 ment is the argu
a2b0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 ment to the.** p
a2c0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 ragma or NULL if
a2d0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 the pragma has
a2e0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 no argument. ^T
a2f0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 he handler for a
a300: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e n.** [SQLITE_FCN
a310: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
a320: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 control can opti
a330: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 onally make the
a340: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a first element.**
a350: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 of the char** a
a360: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f rgument point to
a370: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e a string obtain
a380: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
a390: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f _mprintf()].** o
a3a0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
a3b0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 and that string
a3c0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 will become the
a3d0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 result of the p
a3e0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 ragma or.** the
a3f0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 error message if
a400: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c the pragma fail
a410: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 s. ^If the.** [S
a420: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a430: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
a440: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
a450: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e _NOTFOUND], then
a460: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 normal .** [PRA
a470: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 GMA] processing
a480: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 continues. ^If
a490: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
a4a0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
a4b0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
a4c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
a4d0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 hen the parser a
a4e0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
a4f0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c ** VFS has handl
a500: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 ed the PRAGMA it
a510: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 self and the par
a520: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 ser generates a
a530: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 no-op.** prepare
a540: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 d statement. ^I
a550: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
a560: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
a570: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
a580: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 .** any result c
a590: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ode other than [
a5a0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 SQLITE_OK] or [S
a5b0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
a5c0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 that means.** t
a5d0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f hat the VFS enco
a5e0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 untered an error
a5f0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 while handling
a600: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 the [PRAGMA] and
a610: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 the.** compilat
a620: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d ion of the PRAGM
a630: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 A fails with an
a640: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 error. ^The [SQ
a650: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
a660: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 A].** file contr
a670: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 ol occurs at the
a680: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 beginning of pr
a690: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 agma statement a
a6a0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a nalysis and so.*
a6b0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 * it is able to
a6c0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 override built-i
a6d0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 n [PRAGMA] state
a6e0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ments..**.** <li
a6f0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a700: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a BUSYHANDLER]].**
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
a720: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d NTL_BUSYHANDLER]
a730: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
a740: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 may be invoked
a750: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 by SQLite on the
a760: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 database file h
a770: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 andle.** shortly
a780: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 after it is ope
a790: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ned in order to
a7a0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d provide a custom
a7b0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 VFS with access
a7c0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 .** to the conne
a7d0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 ctions busy-hand
a7e0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 ler callback. Th
a7f0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 e argument is of
a800: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a type (void **).
a810: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 ** - an array of
a820: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 two (void *) va
a830: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 lues. The first
a840: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c (void *) actuall
a850: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 y points.** to a
a860: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 function of typ
a870: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 e (int (*)(void
a880: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f *)). In order to
a890: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e invoke the conn
a8a0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d ections.** busy-
a8b0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 handler, this fu
a8c0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 nction should be
a8d0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 invoked with th
a8e0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a e second (void *
a8f0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 ) in.** the arra
a900: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 y as the only ar
a910: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 gument. If it re
a920: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
a930: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 then the operati
a940: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 on.** should be
a950: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 retried. If it r
a960: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 eturns zero, the
a970: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 custom VFS shou
a980: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a ld abandon the.*
a990: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 * current operat
a9a0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ion..**.** <li>[
a9b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 [SQLITE_FCNTL_TE
a9c0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 MPFILENAME]].**
a9d0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e ^Application can
a9e0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c invoke the [SQL
a9f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 ITE_FCNTL_TEMPFI
aa00: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e LENAME] file-con
aa10: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 trol.** to have
aa20: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 SQLite generate
aa30: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 a.** temporary f
aa40: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 ilename using th
aa50: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d e same algorithm
aa60: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 that is followe
aa70: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a d to generate.**
aa80: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e temporary filen
aa90: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 ames for TEMP ta
aaa0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 bles and other i
aab0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 nternal uses. T
aac0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 he.** argument s
aad0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a hould be a char*
aae0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 * which will be
aaf0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
ab00: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 filename.** writ
ab10: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
ab20: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
ab30: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
ab40: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 . The caller sh
ab50: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b ould.** invoke [
ab60: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
ab70: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f on the result to
ab80: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 avoid a memory
ab90: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e leak..**.** <li>
aba0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [[SQLITE_FCNTL_M
abb0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 MAP_SIZE]].** Th
abc0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
abd0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 MMAP_SIZE] file
abe0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
abf0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 to query or set
ac00: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e the.** maximum n
ac10: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 umber of bytes t
ac20: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 hat will be used
ac30: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 for memory-mapp
ac40: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 ed I/O..** The a
ac50: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
ac60: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 nter to a value
ac70: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f of type sqlite3_
ac80: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 int64 that.** is
ac90: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 an advisory max
aca0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 imum number of b
acb0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
acc0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 to memory map.
acd0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 The.** pointer
ace0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
acf0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 ith the old valu
ad00: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 e. The limit is
ad10: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a not changed if.
ad20: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 ** the value ori
ad30: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 ginally pointed
ad40: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 to is negative,
ad50: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 and so the curre
ad60: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e nt limit .** can
ad70: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 be queried by p
ad80: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e assing in a poin
ad90: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 ter to a negativ
ada0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a e number. This.
adb0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 ** file-control
adc0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
add0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ly to implement
ade0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
adf0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a e]..**.** </ul>.
ae00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
ae10: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
ae20: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
ae30: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
ae40: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
ae50: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 LE 2
ae60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ae70: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
ae80: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a E 3.
ae90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
aea0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
aeb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 4.#
aec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
aed0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 NTL_SIZE_HINT
aee0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
aef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
af00: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 TL_CHUNK_SIZE
af10: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
af20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
af30: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 L_FILE_POINTER
af40: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
af50: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
af60: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 _SYNC_OMITTED
af70: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 8.#defi
af80: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
af90: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 WIN32_AV_RETRY
afa0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
afb0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
afc0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 ERSIST_WAL
afd0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 10.#define
afe0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 SQLITE_FCNTL_OV
aff0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 ERWRITE
b000: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 11.#define
b010: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
b020: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 NAME
b030: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 12.#define S
b040: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
b050: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
b060: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 13.#define SQ
b070: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
b080: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
b090: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 14.#define SQL
b0a0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
b0b0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 NDLER
b0c0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 15.#define SQLI
b0d0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
b0e0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 ENAME
b0f0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 16.#define SQLIT
b100: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
b110: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 E 1
b120: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 8../*.** CAPI3RE
b130: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a F: Mutex Handle.
b140: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 **.** The mutex
b150: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 module within SQ
b160: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 Lite defines [sq
b170: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 lite3_mutex] to
b180: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 be an.** abstrac
b190: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 t type for a mut
b1a0: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 ex object. The
b1b0: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 SQLite core neve
b1c0: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 r looks.** at th
b1d0: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
b1e0: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 sentation of an
b1f0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e [sqlite3_mutex].
b200: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 It only.** dea
b210: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 ls with pointers
b220: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
b230: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a _mutex] object..
b240: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 **.** Mutexes ar
b250: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 e created using
b260: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 [sqlite3_mutex_a
b270: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 lloc()]..*/.type
b280: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
b290: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 e3_mutex sqlite3
b2a0: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _mutex;../*.** C
b2b0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
b2c0: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a rface Object.**.
b2d0: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
b2e0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
b2f0: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
b300: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
b310: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 etween.** the SQ
b320: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 Lite core and th
b330: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
b340: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
b350: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 The "vfs".** in
b360: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
b370: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f object stands fo
b380: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 r "virtual file
b390: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a system". See.**
b3a0: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 the [VFS | VFS
b3b0: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
b3c0: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 or further infor
b3d0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 mation..**.** Th
b3e0: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 e value of the i
b3f0: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 Version field is
b400: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 initially 1 but
b410: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 may be larger i
b420: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 n.** future vers
b430: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 ions of SQLite.
b440: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c Additional fiel
b450: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
b460: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 ed to this.** ob
b470: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 ject when the iV
b480: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 ersion value is
b490: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 increased. Note
b4a0: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 that the struct
b4b0: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 ure.** of the sq
b4c0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 lite3_vfs object
b4d0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
b4e0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 transaction betw
b4f0: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 een.** SQLite ve
b500: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 rsion 3.5.9 and
b510: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 3.6.0 and yet th
b520: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
b530: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 was not.** modi
b540: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fied..**.** The
b550: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 szOsFile field i
b560: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
b570: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 e subclassed [sq
b580: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 lite3_file].** s
b590: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 tructure used by
b5a0: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 this VFS. mxPa
b5b0: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 thname is the ma
b5c0: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a ximum length of.
b5d0: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e ** a pathname in
b5e0: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a this VFS..**.**
b5f0: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 Registered sqli
b600: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 te3_vfs objects
b610: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 are kept on a li
b620: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 nked list formed
b630: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 by.** the pNext
b640: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b pointer. The [
b650: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 sqlite3_vfs_regi
b660: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b ster()].** and [
b670: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 sqlite3_vfs_unre
b680: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 gister()] interf
b690: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 aces manage this
b6a0: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 list.** in a th
b6b0: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 read-safe way.
b6c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
b6d0: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 _find()] interfa
b6e0: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 ce.** searches t
b6f0: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 he list. Neithe
b700: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
b710: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 n code nor the V
b720: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 FS.** implementa
b730: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 tion should use
b740: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 the pNext pointe
b750: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 r..**.** The pNe
b760: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 xt field is the
b770: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 only field in th
b780: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
b790: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 structure that
b7a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 SQLite will ever
b7b0: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 modify. SQLite
b7c0: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 will only acces
b7d0: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 s.** or modify t
b7e0: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 his field while
b7f0: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 holding a partic
b800: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 ular static mute
b810: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 x..** The applic
b820: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 ation should nev
b830: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 er modify anythi
b840: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 ng within the sq
b850: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a lite3_vfs.** obj
b860: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a ect once the obj
b870: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 ect has been reg
b880: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 istered..**.** T
b890: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 he zName field h
b8a0: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 olds the name of
b8b0: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e the VFS module.
b8c0: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a The name must.
b8d0: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 ** be unique acr
b8e0: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 oss all VFS modu
b8f0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c les..**.** [[sql
b900: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d ite3_vfs.xOpen]]
b910: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 .** ^SQLite guar
b920: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
b930: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
b940: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 ter to xOpen.**
b950: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c is either a NULL
b960: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 pointer or stri
b970: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ng obtained.** f
b980: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d rom xFullPathnam
b990: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 e() with an opti
b9a0: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 onal suffix adde
b9b0: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 d..** ^If a suff
b9c0: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 ix is added to t
b9d0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 he zFilename par
b9e0: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a ameter, it will.
b9f0: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 ** consist of a
ba00: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 single "-" chara
ba10: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 cter followed by
ba20: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a no more than.**
ba30: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 11 alphanumeric
ba40: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 and/or "-" char
ba50: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 acters..** ^SQLi
ba60: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 te further guara
ba70: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 ntees that.** th
ba80: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 e string will be
ba90: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 valid and uncha
baa0: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 nged until xClos
bab0: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 e() is.** called
bac0: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 . Because of the
bad0: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e previous senten
bae0: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 ce,.** the [sqli
baf0: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 te3_file] can sa
bb00: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 fely store a poi
bb10: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 nter to the.** f
bb20: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 ilename if it ne
bb30: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 eds to remember
bb40: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 the filename for
bb50: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a some reason..**
bb60: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d If the zFilenam
bb70: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
bb80: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 Open is a NULL p
bb90: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 ointer then xOpe
bba0: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 n.** must invent
bbb0: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 its own tempora
bbc0: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 ry name for the
bbd0: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 file. ^Whenever
bbe0: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 the .** xFilena
bbf0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 me parameter is
bc00: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 NULL it will als
bc10: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 o be the case th
bc20: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 at the.** flags
bc30: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 parameter will i
bc40: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f nclude [SQLITE_O
bc50: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
bc60: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c E]..**.** The fl
bc70: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
bc80: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 xOpen() includes
bc90: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e all bits set in
bca0: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 .** the flags ar
bcb0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 gument to [sqlit
bcc0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 e3_open_v2()].
bcd0: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f Or if [sqlite3_o
bce0: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 pen()].** or [sq
bcf0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
bd00: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c is used, then fl
bd10: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 ags includes at
bd20: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 least.** [SQLITE
bd30: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
bd40: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f | [SQLITE_OPEN_
bd50: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 CREATE]. .** If
bd60: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 xOpen() opens a
bd70: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 file read-only t
bd80: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 hen it sets *pOu
bd90: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 tFlags to.** inc
bda0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
bdb0: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 N_READONLY]. Ot
bdc0: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 her bits in *pOu
bdd0: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 tFlags may be se
bde0: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 t..**.** ^(SQLit
bdf0: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 e will also add
be00: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
be10: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
be20: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c e xOpen().** cal
be30: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 l, depending on
be40: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 the object being
be50: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c opened:.**.** <
be60: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 ul>.** <li> [SQ
be70: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
be80: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
be90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
bea0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
beb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d [SQLITE_OPEN_TEM
bec0: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b P_DB].** <li> [
bed0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
bee0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
bef0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
bf00: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a TRANSIENT_DB].**
bf10: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
bf20: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a PEN_SUBJOURNAL].
bf30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
bf40: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 _OPEN_MASTER_JOU
bf50: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
bf60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d SQLITE_OPEN_WAL]
bf70: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a .** </ul>)^.**.*
bf80: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 * The file I/O i
bf90: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 mplementation ca
bfa0: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 n use the object
bfb0: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a type flags to.*
bfc0: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 * change the way
bfd0: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 it deals with f
bfe0: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 iles. For examp
bff0: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
c000: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 on.** that does
c010: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 not care about c
c020: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 rash recovery or
c030: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 rollback might
c040: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e make.** the open
c050: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 of a journal fi
c060: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 le a no-op. Wri
c070: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 tes to this jour
c080: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 nal would.** als
c090: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 o be no-ops, and
c0a0: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 any attempt to
c0b0: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c read the journal
c0c0: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a would return.**
c0d0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 SQLITE_IOERR.
c0e0: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 Or the implement
c0f0: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f ation might reco
c100: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 gnize that a dat
c110: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 abase.** file wi
c120: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 ll be doing page
c130: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 -aligned sector
c140: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 reads and writes
c150: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 in a random.**
c160: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 order and set up
c170: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 its I/O subsyst
c180: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a em accordingly..
c190: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 **.** SQLite mig
c1a0: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ht also add one
c1b0: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
c1c0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
c1d0: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a pen method:.**.*
c1e0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
c1f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
c200: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c TEONCLOSE].** <l
c210: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
c220: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f EXCLUSIVE].** </
c230: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 ul>.**.** The [S
c240: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
c250: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d EONCLOSE] flag m
c260: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 eans the file sh
c270: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 ould be.** delet
c280: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c ed when it is cl
c290: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c osed. ^The [SQL
c2a0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
c2b0: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 NCLOSE].** will
c2c0: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 be set for TEMP
c2d0: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 databases and th
c2e0: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 eir journals, tr
c2f0: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 ansient.** datab
c300: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 ases, and subjou
c310: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rnals..**.** ^Th
c320: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 e [SQLITE_OPEN_E
c330: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 XCLUSIVE] flag i
c340: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e s always used in
c350: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 conjunction.**
c360: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
c370: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c _OPEN_CREATE] fl
c380: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f ag, which are bo
c390: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 th directly.** a
c3a0: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 nalogous to the
c3b0: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 O_EXCL and O_CRE
c3c0: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 AT flags of the
c3d0: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 POSIX open().**
c3e0: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 API. The SQLITE
c3f0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 _OPEN_EXCLUSIVE
c400: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 flag, when paire
c410: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 d with the .** S
c420: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
c430: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e E, is used to in
c440: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 dicate that file
c450: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a should always.*
c460: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e * be created, an
c470: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 d that it is an
c480: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 error if it alre
c490: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 ady exists..** I
c4a0: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 t is <i>not</i>
c4b0: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
c4c0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
c4d0: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 be opened .** f
c4e0: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 or exclusive acc
c4f0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c ess..**.** ^At l
c500: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 east szOsFile by
c510: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 tes of memory ar
c520: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 e allocated by S
c530: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 QLite.** to hold
c540: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 the [sqlite3_f
c550: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 ile] structure p
c560: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 assed as the thi
c570: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 rd.** argument t
c580: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f o xOpen. The xO
c590: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 pen method does
c5a0: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 not have to.** a
c5b0: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 llocate the stru
c5c0: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 cture; it should
c5d0: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e just fill it in
c5e0: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 . Note that.**
c5f0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 the xOpen method
c600: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 must set the sq
c610: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
c620: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a ods to either.**
c630: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 a valid [sqlite
c640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
c650: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e ject or to NULL.
c660: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a xOpen must do.
c670: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 ** this even if
c680: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 the open fails.
c690: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 SQLite expects
c6a0: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 that the sqlite3
c6b0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a _file.pMethods.*
c6c0: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 * element will b
c6d0: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f e valid after xO
c6e0: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 pen returns rega
c6f0: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 rdless of the su
c700: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c ccess.** or fail
c710: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e ure of the xOpen
c720: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 call..**.** [[s
c730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 qlite3_vfs.xAcce
c740: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 ss]].** ^The fla
c750: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
c760: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 Access() may be
c770: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 [SQLITE_ACCESS_E
c780: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 XISTS].** to tes
c790: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 t for the existe
c7a0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f nce of a file, o
c7b0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
c7c0: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a _READWRITE] to.*
c7d0: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 * test whether a
c7e0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
c7f0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 e and writable,
c800: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 or [SQLITE_ACCES
c810: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 S_READ].** to te
c820: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c st whether a fil
c830: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 e is at least re
c840: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 adable. The fi
c850: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 le can be a.** d
c860: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 irectory..**.**
c870: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 ^SQLite will alw
c880: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 ays allocate at
c890: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 least mxPathname
c8a0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 +1 bytes for the
c8b0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 .** output buffe
c8c0: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e r xFullPathname.
c8d0: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 The exact size
c8e0: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 of the output b
c8f0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f uffer.** is also
c900: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 passed as a par
c910: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 ameter to both
c920: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 methods. If the
c930: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
c940: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e is not large en
c950: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 ough, [SQLITE_CA
c960: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 NTOPEN] should b
c970: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 e returned. Sinc
c980: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e e this is.** han
c990: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 dled as a fatal
c9a0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c error by SQLite,
c9b0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 vfs implementat
c9c0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 ions should ende
c9d0: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 avor.** to preve
c9e0: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 nt this by setti
c9f0: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f ng mxPathname to
ca00: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 a sufficiently
ca10: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a large value..**.
ca20: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
ca30: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 ss(), xSleep(),
ca40: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 xCurrentTime(),
ca50: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 and xCurrentTime
ca60: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 Int64().** inter
ca70: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 faces are not st
ca80: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 rictly a part of
ca90: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c the filesystem,
caa0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a but they are.**
cab0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 included in the
cac0: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 VFS structure f
cad0: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e or completeness.
cae0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e .** The xRandomn
caf0: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 ess() function a
cb00: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 ttempts to retur
cb10: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a n nBytes bytes.*
cb20: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 * of good-qualit
cb30: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 y randomness int
cb40: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 o zOut. The ret
cb50: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 urn value is.**
cb60: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 the actual numbe
cb70: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 r of bytes of ra
cb80: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
cb90: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 d..** The xSleep
cba0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 () method causes
cbb0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 the calling thr
cbc0: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 ead to sleep for
cbd0: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 at.** least the
cbe0: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f number of micro
cbf0: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 seconds given.
cc00: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d ^The xCurrentTim
cc10: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 e().** method re
cc20: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 turns a Julian D
cc30: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 ay Number for th
cc40: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 e current date a
cc50: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 nd time as.** a
cc60: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
cc70: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 alue..** ^The xC
cc80: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
cc90: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 ) method returns
cca0: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c , as an integer,
ccb0: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 the Julian.** D
ccc0: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 ay Number multip
ccd0: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 lied by 86400000
cce0: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 (the number of
ccf0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 milliseconds in
cd00: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 .** a 24-hour da
cd10: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 y). .** ^SQLite
cd20: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 will use the xC
cd30: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
cd40: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 ) method to get
cd50: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 the current.** d
cd60: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 ate and time if
cd70: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 that method is a
cd80: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 vailable (if iVe
cd90: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a rsion is 2 or .*
cda0: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 * greater and th
cdb0: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 e function point
cdc0: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 er is not NULL)
cdd0: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 and will fall ba
cde0: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e ck.** to xCurren
cdf0: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 tTime() if xCurr
ce00: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 entTimeInt64() i
ce10: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a s unavailable..*
ce20: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 *.** ^The xSetSy
ce30: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 stemCall(), xGet
ce40: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e SystemCall(), an
ce50: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c d xNestSystemCal
ce60: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a l() interfaces.*
ce70: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 * are not used b
ce80: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 y the SQLite cor
ce90: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e e. These option
cea0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
ceb0: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 e provided.** by
cec0: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 some VFSes to f
ced0: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e acilitate testin
cee0: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 g of the VFS cod
cef0: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 e. By overriding
cf00: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c .** system call
cf10: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 s with functions
cf20: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 under its contr
cf30: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 ol, a test progr
cf40: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 am can.** simula
cf50: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 te faults and er
cf60: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 ror conditions t
cf70: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 hat would otherw
cf80: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 ise be difficult
cf90: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c .** or impossibl
cfa0: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 e to induce. Th
cfb0: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 e set of system
cfc0: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 calls that can b
cfd0: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 e overridden.**
cfe0: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 varies from one
cff0: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 VFS to another,
d000: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 and from one ver
d010: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 sion of the same
d020: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e VFS to the.** n
d030: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
d040: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 ns that use thes
d050: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 e interfaces mus
d060: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f t be prepared fo
d070: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 r any.** or all
d080: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 of these interfa
d090: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f ces to be NULL o
d0a0: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 r for their beha
d0b0: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a vior to change.*
d0c0: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 * from one relea
d0d0: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 se to the next.
d0e0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 Applications mu
d0f0: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 st not attempt t
d100: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 o access.** any
d110: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 of these methods
d120: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e if the iVersion
d130: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c of the VFS is l
d140: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 ess than 3..*/.t
d150: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
d160: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 lite3_vfs sqlite
d170: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 3_vfs;.typedef v
d180: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 oid (*sqlite3_sy
d190: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 scall_ptr)(void)
d1a0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
d1b0: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 _vfs {. int iVe
d1c0: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 rsion;
d1d0: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 /* Structure v
d1e0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 ersion number (c
d1f0: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 urrently 3) */.
d200: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 int szOsFile;
d210: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a /* Siz
d220: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 e of subclassed
d230: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a sqlite3_file */.
d240: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 int mxPathname
d250: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 ; /* Ma
d260: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e ximum file pathn
d270: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 ame length */.
d280: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 sqlite3_vfs *pNe
d290: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 xt; /* Next
d2a0: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 registered VFS
d2b0: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
d2c0: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a *zName; /*
d2d0: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 Name of this vi
d2e0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 rtual file syste
d2f0: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 m */. void *pAp
d300: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 pData;
d310: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 /* Pointer to ap
d320: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 plication-specif
d330: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 ic data */. int
d340: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 (*xOpen)(sqlite
d350: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
d360: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 ar *zName, sqlit
d370: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 e3_file*,.
d380: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 int fla
d390: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 gs, int *pOutFla
d3a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 gs);. int (*xDe
d3b0: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lete)(sqlite3_vf
d3c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
d3d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 zName, int syncD
d3e0: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 ir);. int (*xAc
d3f0: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 cess)(sqlite3_vf
d400: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
d410: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 zName, int flags
d420: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b , int *pResOut);
d430: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 . int (*xFullPa
d440: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f thname)(sqlite3_
d450: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
d460: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 *zName, int nOu
d470: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a t, char *zOut);.
d480: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 void *(*xDlOpe
d490: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c n)(sqlite3_vfs*,
d4a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 const char *zFi
d4b0: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 lename);. void
d4c0: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 (*xDlError)(sqli
d4d0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
d4e0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d yte, char *zErrM
d4f0: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a sg);. void (*(*
d500: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f xDlSym)(sqlite3_
d510: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 vfs*,void*, cons
d520: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 t char *zSymbol)
d530: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 )(void);. void
d540: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 (*xDlClose)(sqli
d550: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 te3_vfs*, void*)
d560: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f ;. int (*xRando
d570: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 mness)(sqlite3_v
d580: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 fs*, int nByte,
d590: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 char *zOut);. i
d5a0: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c nt (*xSleep)(sql
d5b0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d ite3_vfs*, int m
d5c0: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 icroseconds);.
d5d0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
d5e0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a me)(sqlite3_vfs*
d5f0: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e , double*);. in
d600: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f t (*xGetLastErro
d610: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c r)(sqlite3_vfs*,
d620: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 int, char *);.
d630: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
d640: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
d650: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 n version 1 of t
d660: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
d670: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 ject. ** defini
d680: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 tion. Those tha
d690: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 t follow are add
d6a0: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 ed in version 2
d6b0: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 or later. */.
d6c0: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 int (*xCurrentTi
d6d0: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 meInt64)(sqlite3
d6e0: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 _vfs*, sqlite3_i
d6f0: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a nt64*);. /*. *
d700: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 * The methods ab
d710: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 ove are in versi
d720: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 ons 1 and 2 of t
d730: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
d740: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 ject.. ** Those
d750: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 below are for v
d760: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 ersion 3 and gre
d770: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 ater.. */. int
d780: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c (*xSetSystemCal
d790: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
d7a0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
d7b0: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 me, sqlite3_sysc
d7c0: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 all_ptr);. sqli
d7d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 te3_syscall_ptr
d7e0: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xGetSystemCall
d7f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
d800: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
d810: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 e);. const char
d820: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 *(*xNextSystemC
d830: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 all)(sqlite3_vfs
d840: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
d850: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a Name);. /*. **
d860: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
d870: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
d880: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f ns 1 through 3 o
d890: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 f the sqlite_vfs
d8a0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 object.. ** Ne
d8b0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 w fields may be
d8c0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 appended in figu
d8d0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 re versions. Th
d8e0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 e iVersion. **
d8f0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 value will incre
d900: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 ment whenever th
d910: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a is happens. . *
d920: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
d930: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 3REF: Flags for
d940: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 the xAccess VFS
d950: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 method.**.** The
d960: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
d970: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 ants can be used
d980: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 as the third pa
d990: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
d9a0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
d9b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
d9c0: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 vfs] object. Th
d9d0: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 ey determine.**
d9e0: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 what kind of per
d9f0: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 missions the xAc
da00: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c cess method is l
da10: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 ooking for..** W
da20: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
da30: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 S_EXISTS, the xA
da40: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 ccess method.**
da50: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 simply checks wh
da60: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 ether the file e
da70: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 xists..** With S
da80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
da90: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 DWRITE, the xAcc
daa0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
dab0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
dac0: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 named directory
dad0: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c is both readabl
dae0: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a e and writable.*
daf0: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 * (in other word
db00: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 s, if files can
db10: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 be added, remove
db20: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 d, and renamed w
db30: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 ithin.** the dir
db40: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 ectory)..** The
db50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
db60: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 ADWRITE constant
db70: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 is currently us
db80: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a ed only by the.*
db90: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 * [temp_store_di
dba0: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c rectory pragma],
dbb0: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 though this cou
dbc0: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 ld change in a f
dbd0: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 uture.** release
dbe0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 of SQLite..** W
dbf0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
dc00: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 S_READ, the xAcc
dc10: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 ess method.** ch
dc20: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 ecks whether the
dc30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c file is readabl
dc40: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 e. The SQLITE_A
dc50: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 CCESS_READ const
dc60: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e ant is.** curren
dc70: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 tly unused, thou
dc80: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 gh it might be u
dc90: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 sed in a future
dca0: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 release of.** SQ
dcb0: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
dcc0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
dcd0: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 XISTS 0.#defi
dce0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 ne SQLITE_ACCESS
dcf0: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f _READWRITE 1 /
dd00: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 * Used by PRAGMA
dd10: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 temp_store_dire
dd20: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ctory */.#define
dd30: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
dd40: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 EAD 2 /*
dd50: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a Unused */../*.**
dd60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
dd70: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 for the xShmLoc
dd80: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a k VFS method.**.
dd90: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
dda0: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e constants defin
ddb0: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f e the various lo
ddc0: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 cking operations
ddd0: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 .** allowed by t
dde0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
ddf0: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 od of [sqlite3_i
de00: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 o_methods]. The
de10: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 .** following ar
de20: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c e the only legal
de30: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 combinations of
de40: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a flags to the.**
de50: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
de60: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
de70: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
de80: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 _LOCK | SQLITE_S
de90: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 HM_SHARED.** <li
dea0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
deb0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
dec0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 EXCLUSIVE.** <li
ded0: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e > SQLITE_SHM_UN
dee0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
def0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
df00: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
df10: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
df20: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f _EXCLUSIVE.** </
df30: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 ul>.**.** When u
df40: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 nlocking, the sa
df50: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 me SHARED or EXC
df60: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 LUSIVE flag must
df70: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a be supplied as.
df80: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 ** was given no
df90: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
dfa0: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 g lock. .**.**
dfb0: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 The xShmLock met
dfc0: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 hod can transiti
dfd0: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 on between unloc
dfe0: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f ked and SHARED o
dff0: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c r.** between unl
e000: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 ocked and EXCLUS
e010: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 IVE. It cannot
e020: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 transition betwe
e030: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 en SHARED.** and
e040: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 EXCLUSIVE..*/.#
e050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
e060: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 M_UNLOCK 1
e070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e080: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 SHM_LOCK
e090: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
e0a0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 E_SHM_SHARED
e0b0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
e0c0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
e0d0: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 E 8../*.** CA
e0e0: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 PI3REF: Maximum
e0f0: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a xShmLock index.*
e100: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
e110: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c k method on [sql
e120: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
e130: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a may use values.
e140: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 ** between 0 and
e150: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e this upper boun
e160: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 d as its "offset
e170: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 " argument..** T
e180: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 he SQLite core w
e190: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 ill never attemp
e1a0: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 t to acquire or
e1b0: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 release a.** loc
e1c0: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 k outside of thi
e1d0: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 s range.*/.#defi
e1e0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c ne SQLITE_SHM_NL
e1f0: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f OCK 8.../
e200: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
e210: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 nitialize The SQ
e220: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a Lite Library.**.
e230: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
e240: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
e250: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 tine initializes
e260: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c the.** SQLite l
e270: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 ibrary. ^The sq
e280: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
e290: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c routine.** deal
e2a0: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f locates any reso
e2b0: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 urces that were
e2c0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
e2d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e2e0: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 )..** These rout
e2f0: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 ines are designe
e300: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 d to aid in proc
e310: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ess initializati
e320: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f on and.** shutdo
e330: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 wn on embedded s
e340: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 ystems. Worksta
e350: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e tion application
e360: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 s using.** SQLit
e370: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f e normally do no
e380: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 t need to invoke
e390: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 either of these
e3a0: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
e3b0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 A call to sqlit
e3c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
e3d0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
e3e0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a " call if it is.
e3f0: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d ** the first tim
e400: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
e410: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
e420: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 d during the lif
e430: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 etime of.** the
e440: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 process, or if i
e450: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 t is the first t
e460: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 ime sqlite3_init
e470: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f ialize() is invo
e480: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 ked.** following
e490: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 a call to sqlit
e4a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
e4b0: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 ^(Only an effect
e4c0: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 ive call.** of s
e4d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
e4e0: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 e() does any ini
e4f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c tialization. Al
e500: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a l other calls.**
e510: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f are harmless no
e520: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 -ops.)^.**.** A
e530: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
e540: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e shutdown() is an
e550: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c "effective" cal
e560: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 l if it is the f
e570: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 irst.** call to
e580: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
e590: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 () since the las
e5a0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
e5b0: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a lize(). ^(Only.
e5c0: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ** an effective
e5d0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
e5e0: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 shutdown() does
e5f0: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 any deinitializa
e600: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 tion..** All oth
e610: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 er valid calls t
e620: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
e630: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 wn() are harmles
e640: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
e650: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
e660: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 itialize() inter
e670: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 face is threadsa
e680: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f fe, but sqlite3_
e690: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 shutdown().** is
e6a0: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 not. The sqlit
e6b0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e e3_shutdown() in
e6c0: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c terface must onl
e6d0: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d y be called from
e6e0: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 a.** single thr
e6f0: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b ead. All open [
e700: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
e710: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c ions] must be cl
e720: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 osed and all.**
e730: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 other SQLite res
e740: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 ources must be d
e750: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 eallocated prior
e760: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 to invoking.**
e770: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
e780: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 ()..**.** Among
e790: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 other things, ^s
e7a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
e7b0: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a e() will invoke.
e7c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
e7d0: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 it(). Similarly
e7e0: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 , ^sqlite3_shutd
e7f0: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e own().** will in
e800: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f voke sqlite3_os_
e810: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 end()..**.** ^Th
e820: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
e830: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 lize() routine r
e840: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
e850: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a K] on success..*
e860: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 * ^If for some r
e870: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 eason, sqlite3_i
e880: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 nitialize() is u
e890: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c nable to initial
e8a0: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 ize.** the libra
e8b0: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 ry (perhaps it i
e8c0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
e8d0: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 cate a needed re
e8e0: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 source such.** a
e8f0: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 s a mutex) it re
e900: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 turns an [error
e910: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e code] other than
e920: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a [SQLITE_OK]..**
e930: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
e940: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f _initialize() ro
e950: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
e960: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 internally by ma
e970: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ny other.** SQLi
e980: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f te interfaces so
e990: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 that an applica
e9a0: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 tion usually doe
e9b0: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a s not need to.**
e9c0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
e9d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 initialize() dir
e9e0: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d ectly. For exam
e9f0: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ple, [sqlite3_op
ea00: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 en()].** calls s
ea10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
ea20: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 e() so the SQLit
ea30: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 e library will b
ea40: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a e automatically.
ea50: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 ** initialized w
ea60: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 hen [sqlite3_ope
ea70: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 n()] is called i
ea80: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 f it has not be
ea90: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 initialized.** a
eaa0: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 lready. ^Howeve
eab0: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 r, if SQLite is
eac0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
ead0: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 e [SQLITE_OMIT_A
eae0: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 UTOINIT].** comp
eaf0: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c ile-time option,
eb00: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 then the automa
eb10: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c tic calls to sql
eb20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
eb30: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 ).** are omitted
eb40: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
eb50: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 tion must call s
eb60: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
eb70: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 e() directly.**
eb80: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
eb90: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
eba0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 interface. For
ebb0: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c maximum portabil
ebc0: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 ity,.** it is re
ebd0: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
ebe0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 pplications alwa
ebf0: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ys invoke sqlite
ec00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
ec10: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 * directly prior
ec20: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 to using any ot
ec30: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
ec40: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 face. Future re
ec50: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c leases.** of SQL
ec60: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 ite may require
ec70: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 this. In other
ec80: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 words, the behav
ec90: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a ior exhibited.**
eca0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
ecb0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 compiled with [S
ecc0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
ecd0: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d NIT] might becom
ece0: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 e the.** default
ecf0: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d behavior in som
ed00: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 e future release
ed10: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
ed20: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 * The sqlite3_os
ed30: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 _init() routine
ed40: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 does operating-s
ed50: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a ystem specific.*
ed60: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e * initialization
ed70: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c of the SQLite l
ed80: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c ibrary. The sql
ed90: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
eda0: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 routine undoes
edb0: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 the effect of sq
edc0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e lite3_os_init().
edd0: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a Typical tasks.
ede0: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 ** performed by
edf0: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 these routines i
ee00: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f nclude allocatio
ee10: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f n or deallocatio
ee20: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 n.** of static r
ee30: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 esources, initia
ee40: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 lization of glob
ee50: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a al variables,.**
ee60: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 setting up a de
ee70: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
ee80: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 fs] module, or s
ee90: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 etting up.** a d
eea0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
eeb0: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 tion using [sqli
eec0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a te3_config()]..*
eed0: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
eee0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
eef0: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 r invoke either
ef00: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
ef10: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
ef20: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c os_end() directl
ef30: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 y. The applicat
ef40: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 ion should only
ef50: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
ef60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
ef70: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nd sqlite3_shutd
ef80: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 own(). The sqli
ef90: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a te3_os_init().**
efa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 interface is ca
efb0: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c lled automatical
efc0: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e ly by sqlite3_in
efd0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a itialize() and.*
efe0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 * sqlite3_os_end
eff0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 () is called by
f000: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
f010: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 (). Appropriate
f020: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
f030: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f ons for sqlite3_
f040: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
f050: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
f060: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f * are built into
f070: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 SQLite when it
f080: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 is compiled for
f090: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f Unix, Windows, o
f0a0: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 r OS/2..** When
f0b0: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c [custom builds |
f0c0: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 built for other
f0d0: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 platforms].** (
f0e0: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 using the [SQLIT
f0f0: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f E_OS_OTHER=1] co
f100: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
f110: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 tion) the applic
f120: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c ation must suppl
f130: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 y a suitable imp
f140: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a lementation for.
f150: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e ** sqlite3_os_in
f160: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 it() and sqlite3
f170: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 _os_end(). An a
f180: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c pplication-suppl
f190: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 ied.** implement
f1a0: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
f1b0: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 _os_init() or sq
f1c0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a lite3_os_end().*
f1d0: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 * must return [S
f1e0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
f1f0: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 cess and some ot
f200: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d her [error code]
f210: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 upon.** failure
f220: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
f230: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
f240: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 );.int sqlite3_s
f250: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 hutdown(void);.i
f260: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e nt sqlite3_os_in
f270: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 it(void);.int sq
f280: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
f290: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
f2a0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
f2b0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
f2c0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ary.**.** The sq
f2d0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
f2e0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
f2f0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
f300: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
f310: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
f320: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
f330: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
f340: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
f350: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
f360: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
f370: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
f380: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
f390: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
f3a0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
f3b0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
f3c0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
f3d0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
f3e0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
f3f0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
f400: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
f410: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
f420: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
f430: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
f440: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
f450: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
f460: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
f470: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
f480: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
f490: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
f4a0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
f4b0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
f4c0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
f4d0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
f4e0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
f4f0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
f500: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
f510: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
f520: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
f530: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
f540: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
f550: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
f560: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
f570: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
f580: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f590: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
f5a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
f5b0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
f5c0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
f5d0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
f5e0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
f5f0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
f600: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
f610: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
f620: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
f630: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
f640: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
f650: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
f660: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
f670: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
f680: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
f690: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
f6a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
f6b0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
f6c0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f ** [configuratio
f6d0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 n option] that d
f6e0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 etermines.** wha
f6f0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 t property of SQ
f700: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f Lite is to be co
f710: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 nfigured. Subse
f720: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a quent arguments.
f730: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ** vary dependin
f740: 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 g on the [config
f750: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a uration option].
f760: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
f770: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
f780: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 ^When a configur
f790: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
f7a0: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
f7b0: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
f7c0: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 QLITE_OK]..** ^I
f7d0: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 f the option is
f7e0: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 unknown or SQLit
f7f0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 e is unable to s
f800: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a et the option.**
f810: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
f820: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ne returns a non
f830: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
f840: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 e]..*/.int sqlit
f850: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e e3_config(int, .
f860: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
f870: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 3REF: Configure
f880: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
f890: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ions.**.** The s
f8a0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
f8b0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
f8c0: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e used to make con
f8d0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
f8e0: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 anges to a [data
f8f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
f900: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
f910: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a is similar to.*
f920: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
f930: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 g()] except that
f940: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 the changes app
f950: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a ly to a single.*
f960: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
f970: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 ection] (specifi
f980: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
f990: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a argument)..**.**
f9a0: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
f9b0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
f9c0: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e db_config(D,V,..
f9d0: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 .) is the.** [S
f9e0: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
f9f0: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 OOKASIDE | confi
fa00: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d guration verb] -
fa10: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 an integer code
fa20: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 .** that indica
fa30: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 tes what aspect
fa40: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
fa50: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
fa60: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 being configured
fa70: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 ..** Subsequent
fa80: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 arguments vary d
fa90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
faa0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
fab0: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 rb..**.** ^Calls
fac0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
fad0: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 onfig() return S
fae0: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 QLITE_OK if and
faf0: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 only if.** the c
fb00: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 all is considere
fb10: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f d successful..*/
fb20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f .int sqlite3_db_
fb30: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c config(sqlite3*,
fb40: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a int op, ...);..
fb50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
fb60: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
fb70: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a n Routines.**.**
fb80: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
fb90: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 this object defi
fba0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
fbb0: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 e between SQLite
fbc0: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 .** and low-leve
fbd0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
fbe0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
fbf0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
fc00: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 is used in only
fc10: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 one place in the
fc20: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
fc30: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 e..** A pointer
fc40: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
fc50: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 f this object is
fc60: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
fc70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
fc80: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 fig()] when the
fc90: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
fca0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 tion is.** [SQLI
fcb0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
fcc0: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
fcd0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 FIG_GETMALLOC].
fce0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 .** By creating
fcf0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
fd00: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 this object.** a
fd10: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f nd passing it to
fd20: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
fd30: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
fd40: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 _MALLOC]).** dur
fd50: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
fd60: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f n, an applicatio
fd70: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
fd80: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
fd90: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
fda0: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 n subsystem for
fdb0: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
fdc0: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 r all of its.**
fdd0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e dynamic memory n
fde0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 eeds..**.** Note
fdf0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d that SQLite com
fe00: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 es with several
fe10: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 [built-in memory
fe20: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 allocators].**
fe30: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 that are perfect
fe40: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 ly adequate for
fe50: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 the overwhelming
fe60: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 majority of app
fe70: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 lications.** and
fe80: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 that this objec
fe90: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c t is only useful
fea0: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 to a tiny minor
feb0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
fec0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 ons.** with spec
fed0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 ialized memory a
fee0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 llocation requir
fef0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 ements. This ob
ff00: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 ject is.** also
ff10: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
ff20: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e ing of SQLite in
ff30: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 order to specif
ff40: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
ff50: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
ff60: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 ator that simula
ff70: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f tes memory out-o
ff80: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
ff90: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 ons in.** order
ffa0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 to verify that S
ffb0: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 QLite recovers g
ffc0: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 racefully from s
ffd0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e uch.** condition
ffe0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 s..**.** The xMa
fff0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 lloc, xRealloc,
10000 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 and xFree method
10010 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
10020 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
10030 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
10040 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 free() functions
10050 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
10060 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
10070 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
10080 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 ees that the sec
10090 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
100a0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 ** xRealloc is a
100b0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 lways a value re
100c0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f turned by a prio
100d0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 r call to xRound
100e0 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 up..**.** xSize
100f0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
10100 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
10110 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
10120 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
10130 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
10140 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
10150 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
10160 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
10170 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
10180 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
10190 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
101a0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
101b0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
101c0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
101d0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
101e0 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
101f0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
10200 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
10210 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
10220 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
10230 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
10240 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
10250 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
10260 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
10270 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
10280 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
10290 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
102a0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
102b0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
102c0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
102d0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
102e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
102f0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
10300 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
10310 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
10320 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
10330 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
10340 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
10350 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
10360 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
10370 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
10380 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
10390 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
103a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
103b0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
103c0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
103d0 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
103e0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
103f0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
10400 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
10410 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
10420 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
10430 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
10440 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
10450 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
10460 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
10470 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
10480 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
10490 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
104a0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
104b0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
104c0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
104d0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
104e0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
104f0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
10500 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
10510 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
10520 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
10530 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
10540 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
10550 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
10560 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
10570 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
10580 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
10590 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
105a0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
105b0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
105c0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
105d0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
105e0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
105f0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
10600 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
10610 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
10620 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
10630 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
10640 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
10650 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
10660 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
10670 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
10680 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
10690 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
106a0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
106b0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
106c0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
106d0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
106e0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
106f0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
10700 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
10710 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
10720 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
10730 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
10740 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
10750 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
10760 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
10770 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
10780 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
10790 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
107a0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
107b0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
107c0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
107d0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
107e0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
107f0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
10800 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
10810 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
10820 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
10830 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
10840 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
10850 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
10860 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
10870 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
10880 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
10890 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
108a0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
108b0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
108c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
108d0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
108e0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
108f0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
10900 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
10910 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
10920 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
10930 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
10940 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
10950 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
10960 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
10970 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
10980 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
10990 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
109a0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
109b0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
109c0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
109d0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
109e0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
109f0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
10a00 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
10a10 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
10a20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
10a30 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
10a40 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
10a50 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
10a60 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
10a70 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
10a80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10a90 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
10aa0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ptions.** KEYWOR
10ab0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 DS: {configurati
10ac0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a on option}.**.**
10ad0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
10ae0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
10af0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
10b00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
10b10 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
10b20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
10b30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
10b40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
10b50 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
10b60 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
10b70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10b80 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
10b90 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
10ba0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
10bb0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
10bc0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
10bd0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
10be0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
10bf0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
10c00 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
10c10 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
10c20 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
10c30 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
10c40 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
10c50 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
10c60 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
10c70 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
10c80 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
10c90 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
10ca0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
10cb0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
10cc0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10cd0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
10ce0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
10cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
10d00 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 NGLETHREAD]] <dt
10d10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
10d20 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
10d30 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
10d40 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
10d50 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
10d60 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
10d70 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
10d80 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e ing mode] to Sin
10d90 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 gle-thread. In
10da0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
10db0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
10dc0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
10dd0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
10de0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
10df0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
10e00 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
10e10 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 read. ^If SQLi
10e20 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10e30 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
10e40 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
10e50 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
10e60 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
10e70 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
10e80 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
10e90 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ble to change th
10ea0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
10eb0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 e] from its defa
10ec0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 ult.** value of
10ed0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e Single-thread an
10ee0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f d so [sqlite3_co
10ef0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
10f00 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urn .** [SQLITE_
10f10 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
10f20 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
10f30 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
10f40 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 READ.** configur
10f50 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
10f60 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
10f70 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
10f80 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
10f90 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
10fa0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
10fb0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
10fc0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
10fd0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
10fe0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
10ff0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
11000 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 e] to Multi-thre
11010 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
11020 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
11030 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
11040 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11050 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
11060 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
11070 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
11080 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
11090 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
110a0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
110b0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
110c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
110d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
110e0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
110f0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
11100 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
11110 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
11120 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
11130 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
11140 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
11150 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
11160 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
11170 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
11180 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
11190 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
111a0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e he same time. ^
111b0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
111c0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
111d0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
111e0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
111f0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
11200 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
11210 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
11220 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
11230 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 t the Multi-thre
11240 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
11250 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
11260 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
11270 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
11280 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
11290 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
112a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
112b0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 TITHREAD configu
112c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
112d0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
112e0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
112f0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 IZED]] <dt>SQLIT
11300 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
11310 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
11320 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
11330 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
11340 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
11350 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
11360 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
11370 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e ] to Serialized.
11380 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
11390 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 this option ena
113a0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
113b0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
113c0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
113d0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
113e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
113f0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
11400 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
11410 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
11420 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
11430 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
11440 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11450 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
11460 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
11470 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
11480 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
11490 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
114a0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
114b0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
114c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
114d0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
114e0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
114f0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
11500 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
11510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
11520 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
11530 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11540 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
11550 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
11560 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 ame time..** ^If
11570 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
11580 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
11590 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
115a0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
115b0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
115c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
115d0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
115e0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
115f0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b the Serialized [
11600 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
11610 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
11620 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
11630 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
11640 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
11650 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
11660 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
11670 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ZED configuratio
11680 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
11690 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
116a0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 NFIG_MALLOC]] <d
116b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
116c0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
116d0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
116e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
116f0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
11700 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
11710 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
11720 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
11730 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
11740 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
11750 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
11760 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
11770 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
11780 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
11790 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
117a0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
117b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
117c0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
117d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
117e0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
117f0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
11800 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
11810 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
11820 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
11830 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
11840 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
11850 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
11860 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
11870 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
11880 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
11890 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
118a0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f NFIG_GETMALLOC</
118b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
118c0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
118d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
118e0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
118f0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
11900 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
11910 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11920 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
11930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
11940 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
11950 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
11960 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
11970 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
11980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
11990 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
119a0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
119b0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
119c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
119d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
119e0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
119f0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
11a00 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
11a10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
11a20 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
11a30 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
11a40 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 for example. </d
11a50 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
11a60 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
11a70 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f US]] <dt>SQLITE_
11a80 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
11a90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
11aa0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
11ab0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
11ac0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e of type int, in
11ad0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a terpreted as a .
11ae0 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 ** boolean, whic
11af0 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
11b00 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
11b10 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 tion of memory a
11b20 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 llocation .** st
11b30 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
11b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11b50 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
11b60 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 e disabled, the
11b70 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 .** following SQ
11b80 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
11b90 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 become non-opera
11ba0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c tional:.** <ul
11bb0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c >.** <li> [sql
11bc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
11bd0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
11be0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
11bf0 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 ghwater()].**
11c00 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f <li> [sqlite3_so
11c10 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
11c20 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
11c30 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a lite3_status()].
11c40 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ** </ul>)^.**
11c50 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 ^Memory allocati
11c60 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
11c70 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
11c80 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 ault unless SQLi
11c90 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
11ca0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
11cb0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 EFAULT_MEMSTATUS
11cc0 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 ]=0 in which cas
11cd0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
11ce0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
11cf0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
11d00 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f y default..** </
11d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11d20 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
11d30 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 H]] <dt>SQLITE_C
11d40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
11d50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
11d60 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
11d70 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
11d80 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
11d90 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
11da0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
11db0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
11dc0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
11dd0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
11de0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
11df0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
11e00 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
11e10 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
11e20 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 will be.** draw
11e30 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 n, the size of e
11e40 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f ach scratch allo
11e50 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 cation (sz),.**
11e60 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 and the maximum
11e70 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 number of scratc
11e80 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e h allocations (N
11e90 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 ). The sz.** ar
11ea0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
11eb0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e multiple of 16.
11ec0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
11ed0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
11ee0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
11ef0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 -byte aligned bu
11f00 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 ffer.** of at le
11f10 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
11f20 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
11f30 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f Lite will use no
11f40 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 more than two s
11f50 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 cratch buffers p
11f60 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a er thread. So.*
11f70 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 * N should be se
11f80 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 t to twice the e
11f90 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 xpected maximum
11fa0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 number of thread
11fb0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 s..** ^SQLite wi
11fc0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 ll never require
11fd0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 a scratch buffe
11fe0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 r that is more t
11ff0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 han 6.** times t
12000 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
12010 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 size. ^If SQLit
12020 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 e needs needs ad
12030 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 ditional.** scra
12040 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e tch memory beyon
12050 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
12060 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 ed by this confi
12070 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c guration option,
12080 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 then .** [sqlit
12090 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c e3_malloc()] wil
120a0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 l be used to obt
120b0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e ain the memory n
120c0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a eeded.</dd>.**.*
120d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
120e0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
120f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12100 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
12110 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
12120 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
12130 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
12140 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
12150 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
12160 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
12170 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
12180 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 default page ca
12190 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
121a0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
121b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
121c0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
121d0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
121e0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
121f0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
12200 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
12210 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
12220 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f CONFIG_PCACHE2 o
12230 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 ption..** There
12240 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
12250 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
12260 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f on: A pointer to
12270 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 8-byte aligned.
12280 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
12290 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
122a0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
122b0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
122c0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
122d0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
122e0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
122f0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
12300 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
12310 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
12320 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
12330 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 32768) plus a l
12340 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 ittle extra for
12350 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
12360 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 der. ^The page
12370 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 header size is 2
12380 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 0 to 40 bytes de
12390 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 pending on.** th
123a0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 e host architect
123b0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 ure. ^It is har
123c0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f mless, apart fro
123d0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d m the wasted mem
123e0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 ory,.** to make
123f0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 sz a little too
12400 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 large. The firs
12410 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
12420 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
12430 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
12440 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
12450 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
12460 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
12470 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
12480 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
12490 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
124a0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
124b0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
124c0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
124d0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
124e0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 cache. ^If add
124f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
12500 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
12510 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
12520 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
12530 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
12540 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
12550 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
12560 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
12570 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
12580 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
12590 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
125a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
125b0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
125c0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
125d0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
125e0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
125f0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
12600 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
12610 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12620 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
12630 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12640 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
12650 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
12660 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
12670 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
12680 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
12690 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 will use.** for
126a0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
126b0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
126c0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e tion needs beyon
126d0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 d those provided
126e0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 .** for by [SQLI
126f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
12700 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 H] and [SQLITE_C
12710 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
12720 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
12730 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
12740 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 An 8-byte aligne
12750 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 d pointer to the
12760 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 memory,.** the
12770 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
12780 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
12790 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
127a0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
127b0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 size..** ^If th
127c0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
127d0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
127e0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
127f0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
12800 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
12810 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
12820 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
12830 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
12840 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
12850 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
12860 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
12870 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
12880 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 IG_MALLOC]. ^If
12890 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
128a0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
128b0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 LL and either [S
128c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
128d0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c SYS3] or.** [SQL
128e0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
128f0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c S5] are defined,
12900 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
12910 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
12920 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
12930 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
12940 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
12950 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12960 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 needs..** The fi
12970 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
12980 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
12990 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
129a0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
129b0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
129c0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
129d0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
129e0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a be undefined..**
129f0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c The minimum all
12a00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 ocation size is
12a10 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e capped at 2**12.
12a20 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 Reasonable valu
12a30 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 es.** for the mi
12a40 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
12a50 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 size are 2**5 t
12a60 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 hrough 2**8.</dd
12a70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12a80 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 _CONFIG_MUTEX]]
12a90 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
12aa0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 G_MUTEX</dt>.**
12ab0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
12ac0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12ad0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12ae0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
12af0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
12b00 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12b10 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
12b20 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 tructure. The a
12b30 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
12b40 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
12b50 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 low-level mutex
12b60 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
12b70 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a used in place.**
12b80 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 the mutex routi
12b90 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
12ba0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 QLite.)^ ^SQLit
12bb0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
12bc0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 f the.** content
12bd0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
12be0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
12bf0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 structure before
12c00 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
12c10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12c20 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 )] returns. ^If
12c30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
12c40 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
12c50 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
12c60 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
12c70 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
12c80 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
12c90 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
12ca0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
12cb0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
12cc0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
12cd0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
12ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
12cf0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
12d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
12d10 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
12d20 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
12d30 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12d40 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
12d50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12d60 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 G_GETMUTEX]] <dt
12d70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
12d80 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
12d90 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
12da0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12db0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12dc0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
12dd0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
12de0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12df0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
12e00 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
12e10 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
12e20 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
12e30 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
12e40 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
12e50 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
12e60 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
12e70 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
12e80 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
12e90 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
12ea0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
12eb0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
12ec0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
12ed0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
12ee0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
12ef0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
12f00 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
12f10 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
12f20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
12f30 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
12f40 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
12f50 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
12f60 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
12f70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
12f80 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
12f90 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
12fa0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
12fb0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
12fc0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
12fd0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
12fe0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
12ff0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13000 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
13010 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
13020 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
13030 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
13040 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
13050 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
13060 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
13070 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
13080 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
13090 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
130a0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
130b0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
130c0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d e default.** mem
130d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
130e0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 or the lookaside
130f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
13100 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 r on each.** [da
13110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
13120 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
13130 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
13140 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
13150 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
13160 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
13170 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
13180 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
13190 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
131a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
131b0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f ion.)^ ^(This o
131c0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
131d0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e * <i>default</i>
131e0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
131f0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
13200 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
13210 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c .** verb to [sql
13220 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
13230 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
13240 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
13250 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
13260 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
13270 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
13280 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
13290 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
132a0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 PCACHE2]] <dt>SQ
132b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
132c0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
132d0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
132e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
132f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
13300 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
13310 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
13320 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
13330 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
13340 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
13350 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
13360 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
13370 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
13380 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d on.)^ ^SQLite m
13390 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
133a0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 he.** object and
133b0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 uses it for pag
133c0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 e cache memory a
133d0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e llocations.</dd>
133e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
133f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
13400 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
13410 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
13420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
13430 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
13440 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
13450 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
13460 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
13470 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
13480 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
13490 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
134a0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
134b0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ** page cache im
134c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
134d0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
134e0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
134f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
13500 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
13510 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
13520 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 <dd> The SQLITE
13530 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
13540 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f on is used to co
13550 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 nfigure the SQLi
13560 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 te.** global [er
13570 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 ror log]..** (^T
13580 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13590 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _LOG option take
135a0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a s two arguments:
135b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a a pointer to a.
135c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 ** function with
135d0 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 a call signatur
135e0 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 e of void(*)(voi
135f0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 d*,int,const cha
13600 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 r*), .** and a p
13610 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 ointer to void.
13620 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ^If the function
13630 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
13640 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 NULL, it is.** i
13650 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 nvoked by [sqlit
13660 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f e3_log()] to pro
13670 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e cess each loggin
13680 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
13690 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f e.** function po
136a0 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 inter is NULL, t
136b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 he [sqlite3_log(
136c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 )] interface bec
136d0 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a omes a no-op..**
136e0 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 ^The void point
136f0 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 er that is the s
13700 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
13710 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
13720 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 LOG is.** passed
13730 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
13740 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
13750 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
13760 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
13770 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 r.** function wh
13780 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 enever that func
13790 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e tion is invoked.
137a0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ^The second pa
137b0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 rameter to.** th
137c0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
137d0 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 n is a copy of t
137e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
137f0 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 er to the corres
13800 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 ponding.** [sqli
13810 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 te3_log()] call
13820 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 and is intended
13830 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 to be a [result
13840 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b code] or an.** [
13850 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
13860 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 code]. ^The thi
13870 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 rd parameter pas
13880 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 sed to the logge
13890 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 r is.** log mess
138a0 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 age after format
138b0 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 ting via [sqlite
138c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 3_snprintf()]..*
138d0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 * The SQLite log
138e0 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 ging interface i
138f0 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b s not reentrant;
13900 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 the logger func
13910 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 tion.** supplied
13920 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
13930 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 ion must not inv
13940 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 oke any SQLite i
13950 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 nterface..** In
13960 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 a multi-threaded
13970 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 application, th
13980 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
13990 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
139a0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 function must be
139b0 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 threadsafe. </d
139c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
139d0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c E_CONFIG_URI]] <
139e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
139f0 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 _URI.** <dd> Thi
13a00 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
13a10 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
13a20 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 of type int. If
13a30 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a non-zero, then.
13a40 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 ** URI handling
13a50 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 is globally enab
13a60 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 led. If the para
13a70 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 meter is zero, t
13a80 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 hen URI handling
13a90 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 .** is globally
13aa0 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 disabled. If URI
13ab0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
13ac0 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 bally enabled, a
13ad0 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 ll filenames.**
13ae0 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
13af0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
13b00 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
13b10 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
13b20 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 ()] or.** specif
13b30 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b ied as part of [
13b40 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 ATTACH] commands
13b50 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
13b60 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 as URIs, regard
13b70 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 less.** of wheth
13b80 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 er or not the [S
13b90 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
13ba0 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e flag is set when
13bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
13bc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
13bd0 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 pened. If it is
13be0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 globally disable
13bf0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 d, filenames are
13c00 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 .** only interpr
13c10 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 eted as URIs if
13c20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f the SQLITE_OPEN_
13c30 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 URI flag is set
13c40 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 when the.** data
13c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
13c60 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 is opened. By de
13c70 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c fault, URI handl
13c80 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a ing is globally.
13c90 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 ** disabled. The
13ca0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d default value m
13cb0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 ay be changed by
13cc0 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 compiling with
13cd0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 the.** [SQLITE_U
13ce0 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 SE_URI] symbol d
13cf0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b efined..**.** [[
13d00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
13d10 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
13d20 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 N]] <dt>SQLITE_C
13d30 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
13d40 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 NDEX_SCAN.** <dd
13d50 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 > This option ta
13d60 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 kes a single int
13d70 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 eger argument wh
13d80 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ich is interpret
13d90 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 ed as.** a boole
13da0 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 an in order to e
13db0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
13dc0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 the use of cove
13dd0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 ring indices for
13de0 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 .** full table s
13df0 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 cans in the quer
13e00 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 y optimizer. Th
13e10 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
13e20 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a g is determined.
13e30 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ** by the [SQLIT
13e40 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 E_ALLOW_COVERING
13e50 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d _INDEX_SCAN] com
13e60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
13e70 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 , or is "on".**
13e80 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d if that compile-
13e90 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f time option is o
13ea0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 mitted..** The a
13eb0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c bility to disabl
13ec0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 e the use of cov
13ed0 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f ering indices fo
13ee0 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 r full table sca
13ef0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 ns.** is because
13f00 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c some incorrectl
13f10 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 y coded legacy a
13f20 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 pplications migh
13f30 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a t malfunction.**
13f40 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 malfunction whe
13f50 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 n the optimizati
13f60 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 on is enabled.
13f70 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 Providing the ab
13f80 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 ility to.** disa
13f90 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 ble the optimiza
13fa0 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 tion allows the
13fb0 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 older, buggy app
13fc0 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f lication code to
13fd0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 work.** without
13fe0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 change even wit
13ff0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 h newer versions
14000 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
14010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14020 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c G_PCACHE]] [[SQL
14030 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
14040 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 ACHE]].** <dt>SQ
14050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14060 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f HE and SQLITE_CO
14070 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a NFIG_GETPCACHE.*
14080 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 * <dd> These opt
14090 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 ions are obsolet
140a0 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 e and should not
140b0 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 be used by new
140c0 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 code..** They ar
140d0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 e retained for b
140e0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
140f0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e bility but are n
14100 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f ow no-ops..** </
14110 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14120 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
14130 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
14140 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a _CONFIG_SQLLOG.*
14150 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
14160 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
14170 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 ble if sqlite is
14180 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
14190 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
141a0 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 ABLE_SQLLOG] pre
141b0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
141c0 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 defined. The fi
141d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rst argument sho
141e0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e uld.** be a poin
141f0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f ter to a functio
14200 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a n of type void(*
14210 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
14220 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e ,const char*, in
14230 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e t)..** The secon
14240 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 d should be of t
14250 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 ype (void*). The
14260 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
14270 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 oked by the libr
14280 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 ary.** in three
14290 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 separate circums
142a0 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 tances, identifi
142b0 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 ed by the value
142c0 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a passed as the.**
142d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
142e0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 r. If the fourth
142f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c parameter is 0,
14300 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
14310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
14320 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
14330 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 econd argument h
14340 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 as just been ope
14350 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 ned. The third a
14360 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 rgument.** point
14370 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f s to a buffer co
14380 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d ntaining the nam
14390 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 e of the main da
143a0 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 tabase file. If
143b0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
143c0 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 rameter is 1, th
143d0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
143e0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 ment that the th
143f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ird parameter.**
14400 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a points to has j
14410 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 ust been execute
14420 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f d. Or, if the fo
14430 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
14440 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 s 2, then.** the
14450 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e connection bein
14460 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 g passed as the
14470 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
14480 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 is being closed
14490 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 . The.** third p
144a0 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 arameter is pass
144b0 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 ed NULL In this
144c0 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c case. An exampl
144d0 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a e of using this.
144e0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
144f0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 option can be s
14500 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 een in the "test
14510 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 _sqllog.c" sourc
14520 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 e file in.** the
14530 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 canonical SQLit
14540 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f e source tree.</
14550 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14560 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
14570 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IZE]].** <dt>SQL
14580 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
14590 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49 SIZE.** <dd>SQLI
145a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
145b0 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 IZE takes two 64
145c0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 -bit integer (sq
145d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c lite3_int64) val
145e0 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 ues.** that are
145f0 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 the default mmap
14600 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 size limit (the
14610 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 default setting
14620 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 for.** [PRAGMA
14630 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 mmap_size]) and
14640 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f the maximum allo
14650 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 wed mmap size li
14660 6d 69 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 mit..** The defa
14670 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 ult setting can
14680 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 be overridden by
14690 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
146a0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a onnection using.
146b0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 ** either the [P
146c0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
146d0 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 command, or by
146e0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
146f0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
14700 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 SIZE] file contr
14710 6f 6c 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d ol. The maximum
14720 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
14730 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 ze.** cannot be
14740 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 changed at run-t
14750 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 ime. Nor may th
14760 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
14770 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 d mmap size.** e
14780 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c xceed the compil
14790 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d e-time maximum m
147a0 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 map size set by
147b0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d the.** [SQLITE_M
147c0 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f AX_MMAP_SIZE] co
147d0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
147e0 6e 2e 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65 n. .** If eithe
147f0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 r argument to th
14800 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 is option is neg
14810 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 ative, then that
14820 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
14830 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 changed to its c
14840 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 ompile-time defa
14850 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f ult..** </dl>.*/
14860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14870 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
14880 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a EAD 1 /* nil *
14890 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
148a0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
148b0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 EAD 2 /* nil
148c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
148d0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
148e0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c ZED 3 /* nil
148f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14900 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
14910 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 4 /* sq
14920 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
14930 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
14940 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
14950 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 ALLOC 5 /*
14960 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14970 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
14980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
14990 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f RATCH 6 /
149a0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
149b0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
149c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
149d0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 PAGECACHE 7
149e0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
149f0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
14a00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14a10 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 G_HEAP
14a20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 8 /* void*, int
14a30 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 nByte, int min
14a40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14a50 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
14a60 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f US 9 /* boo
14a70 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 lean */.#define
14a80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
14a90 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f TEX 10 /
14aa0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f * sqlite3_mutex_
14ab0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
14ac0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14ad0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 G_GETMUTEX 1
14ae0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 1 /* sqlite3_mu
14af0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
14b00 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 /* previously SQ
14b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e LITE_CONFIG_CHUN
14b20 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 KALLOC 12 which
14b30 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a is now unused. *
14b40 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 / .#define SQLIT
14b50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
14b60 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 DE 13 /* int
14b70 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
14b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
14b90 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f ACHE 14 /
14ba0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 * no-op */.#defi
14bb0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
14bc0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 _GETPCACHE 15
14bd0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 /* no-op */.#d
14be0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
14bf0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 FIG_LOG
14c00 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 16 /* xFunc, v
14c10 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
14c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
14c30 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f I 17 /
14c40 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 * int */.#define
14c50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
14c60 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 CACHE2 18
14c70 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
14c80 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
14c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
14ca0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
14cb0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 19 /* sqlite3
14cc0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
14cd0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
14ce0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
14cf0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 ING_INDEX_SCAN 2
14d00 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 0 /* int */.#de
14d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
14d20 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 IG_SQLLOG
14d30 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 21 /* xSqllog,
14d40 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
14d50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
14d60 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 MAP_SIZE 22
14d70 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 /* sqlite3_int64
14d80 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
14d90 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
14da0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
14db0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 nection Configur
14dc0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
14dd0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
14de0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
14df0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
14e00 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14e10 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
14e20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
14e30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
14e40 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
14e50 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
14e60 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
14e70 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
14e80 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
14e90 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
14ea0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
14eb0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
14ec0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14ed0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
14ee0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
14ef0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
14f00 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
14f10 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
14f20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
14f30 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
14f40 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
14f50 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 all worked. ^Th
14f60 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
14f70 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
14f80 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
14f90 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
14fa0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
14fb0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
14fc0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
14fd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
14fe0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
14ff0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
15000 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
15010 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
15020 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
15030 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 ion takes three
15040 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
15050 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
15060 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f ine the .** [loo
15070 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
15080 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
15090 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b ration for the [
150a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
150b0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 ion]..** ^The fi
150c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
150d0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
150e0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
150f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
15100 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 ** pointer to a
15110 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f memory buffer to
15120 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 use for lookasi
15130 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 de memory..** ^T
15140 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
15150 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 t after the SQLI
15160 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
15170 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 ASIDE verb.** ma
15180 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 y be NULL in whi
15190 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 ch case SQLite w
151a0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 ill allocate the
151b0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 .** lookaside bu
151c0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e ffer itself usin
151d0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
151e0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e c()]. ^The secon
151f0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
15200 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
15210 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
15220 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 er slot. ^The t
15230 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
15240 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
15250 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 * slots. The si
15260 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
15270 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
15280 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 gument must be g
15290 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f reater than.** o
152a0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 r equal to the p
152b0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 roduct of the se
152c0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 cond and third a
152d0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 rguments. The b
152e0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 uffer.** must be
152f0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
15300 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 -byte boundary.
15310 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 ^If the second
15320 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 argument to.** S
15330 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
15340 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 OOKASIDE is not
15350 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c a multiple of 8,
15360 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c it is internall
15370 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 y.** rounded dow
15380 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d n to the next sm
15390 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f aller multiple o
153a0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b f 8. ^(The look
153b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 aside memory.**
153c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
153d0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e r a database con
153e0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 nection can only
153f0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e be changed when
15400 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 that.** connect
15410 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 ion is not curre
15420 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 ntly using looka
15430 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 side memory, or
15440 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a in other words.*
15450 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 * when the "curr
15460 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 ent value" retur
15470 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
15480 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c e3_db_status](D,
15490 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
154a0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 OOKASIDE],...) i
154b0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 s zero..** Any a
154c0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 ttempt to change
154d0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d the lookaside m
154e0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 emory configurat
154f0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 ion when lookasi
15500 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 de.** memory is
15510 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 in use leaves th
15520 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
15530 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 unchanged and re
15540 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 turns .** [SQLIT
15550 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a E_BUSY].)^</dd>.
15560 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
15570 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
15580 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _FKEY</dt>.** <d
15590 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
155a0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
155b0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 e or disable the
155c0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a enforcement of.
155d0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 ** [foreign key
155e0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 constraints]. T
155f0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
15600 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
15610 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
15620 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
15630 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
15640 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
15650 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
15660 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 t,.** positive t
15670 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f o enable FK enfo
15680 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 rcement or negat
15690 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 ive to leave FK
156a0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 enforcement.** u
156b0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 nchanged. The s
156c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
156d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
156e0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
156f0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
15700 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
15710 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 dicate whether F
15720 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 K enforcement is
15730 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f off or on.** fo
15740 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
15750 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
15760 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
15770 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
15780 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
15790 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d the FK enforcem
157a0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e ent setting is n
157b0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
157c0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
157d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
157e0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
157f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
15800 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
15810 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
15820 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 disable [CREATE
15830 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
15840 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 rs]..** There sh
15850 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 ould be two addi
15860 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
15870 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
15880 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e rgument is an in
15890 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 teger which is 0
158a0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 to disable trig
158b0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 gers,.** positiv
158c0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 e to enable trig
158d0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 gers or negative
158e0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 to leave the se
158f0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e tting unchanged.
15900 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
15910 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
15920 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
15930 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
15940 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
15950 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
15960 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 whether triggers
15970 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 are disabled or
15980 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c enabled.** foll
15990 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
159a0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
159b0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 ameter may be a
159c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
159d0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 .** which case t
159e0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 he trigger setti
159f0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
15a00 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
15a10 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 *.** </dl>.*/.#d
15a20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
15a30 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
15a40 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 1001 /* v
15a50 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a oid* int int */.
15a60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
15a70 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
15a80 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a KEY 1002 /*
15a90 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
15aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
15ab0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 NFIG_ENABLE_TRIG
15ac0 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e GER 1003 /* in
15ad0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a t int* */.../*.*
15ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 * CAPI3REF: Enab
15af0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 le Or Disable Ex
15b00 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f tended Result Co
15b10 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 des.**.** ^The s
15b20 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
15b30 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 result_codes() r
15b40 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f outine enables o
15b50 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a r disables the.*
15b60 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 * [extended resu
15b70 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 lt codes] featur
15b80 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 e of SQLite. ^Th
15b90 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c e extended resul
15ba0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 t.** codes are d
15bb0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 isabled by defau
15bc0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 lt for historica
15bd0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e l compatibility.
15be0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
15bf0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
15c00 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 codes(sqlite3*,
15c10 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a int onoff);../*.
15c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 ** CAPI3REF: Las
15c30 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a t Insert Rowid.*
15c40 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 *.** ^Each entry
15c50 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 in an SQLite ta
15c60 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 ble has a unique
15c70 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 64-bit signed.*
15c80 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 * integer key ca
15c90 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 lled the [ROWID
15ca0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 | "rowid"]. ^The
15cb0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 rowid is always
15cc0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 available.** as
15cd0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 an undeclared c
15ce0 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 olumn named ROWI
15cf0 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 D, OID, or _ROWI
15d00 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 D_ as long as th
15d10 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 ose.** names are
15d20 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 not also used b
15d30 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 y explicitly dec
15d40 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e lared columns. ^
15d50 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 If.** the table
15d60 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 has a column of
15d70 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 type [INTEGER PR
15d80 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 IMARY KEY] then
15d90 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 that column.** i
15da0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 s another alias
15db0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a for the rowid..*
15dc0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
15dd0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ne returns the [
15de0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f rowid] of the mo
15df0 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 st recent.** suc
15e00 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
15e10 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 into the databa
15e20 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 se from the [dat
15e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
15e40 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 ].** in the firs
15e50 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 t argument. ^As
15e60 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 of SQLite versi
15e70 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 on 3.7.7, this r
15e80 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 outines.** recor
15e90 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 ds the last inse
15ea0 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 rt rowid of both
15eb0 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 ordinary tables
15ec0 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 and [virtual ta
15ed0 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f bles]..** ^If no
15ee0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
15ef0 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 ERT]s.** have ev
15f00 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 er occurred on t
15f10 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e hat database con
15f20 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 nection, zero is
15f30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
15f40 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 ^(If an [INSERT
15f50 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 ] occurs within
15f60 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 a trigger or wit
15f70 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 hin a [virtual t
15f80 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c able].** method,
15f90 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
15fa0 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 ne will return t
15fb0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
15fc0 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f e inserted.** ro
15fd0 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 w as long as the
15fe0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 trigger or virt
15ff0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 ual table method
16000 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
16010 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 But once the tri
16020 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 gger or virtual
16030 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 table method end
16040 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 s, the value ret
16050 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 urned .** by thi
16060 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 s routine revert
16070 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 s to what it was
16080 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 before the trig
16090 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a ger or virtual.*
160a0 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 * table method b
160b0 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 egan.)^.**.** ^A
160c0 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 n [INSERT] that
160d0 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 fails due to a c
160e0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
160f0 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 ion is not a.**
16100 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
16110 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 RT] and does not
16120 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
16130 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 e returned by th
16140 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 is.** routine.
16150 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 ^Thus INSERT OR
16160 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 FAIL, INSERT OR
16170 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f IGNORE, INSERT O
16180 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 R ROLLBACK,.** a
16190 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f nd INSERT OR ABO
161a0 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 RT make no chang
161b0 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e es to the return
161c0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a value of this.*
161d0 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 * routine when t
161e0 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 heir insertion f
161f0 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e ails. ^(When IN
16200 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a SERT OR REPLACE.
16210 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 ** encounters a
16220 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
16230 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f tion, it does no
16240 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 t fail. The.**
16250 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 INSERT continues
16260 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 to completion a
16270 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f fter deleting ro
16280 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a ws that caused.*
16290 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 * the constraint
162a0 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 problem so INSE
162b0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 RT OR REPLACE wi
162c0 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 ll always change
162d0 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 .** the return v
162e0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 alue of this int
162f0 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 erface.)^.**.**
16300 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 ^For the purpose
16310 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e s of this routin
16320 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 e, an [INSERT] i
16330 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a s considered to.
16340 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c ** be successful
16350 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 even if it is s
16360 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c ubsequently roll
16370 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
16380 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
16390 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 accessible to SQ
163a0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 L statements via
163b0 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e the.** [last_in
163c0 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c sert_rowid() SQL
163d0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
163e0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
163f0 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 thread performs
16400 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f a new [INSERT] o
16410 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 n the same.** da
16420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16430 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c n while the [sql
16440 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
16450 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e _rowid()].** fun
16460 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
16470 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 and thus change
16480 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 s the last inser
16490 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 t [rowid],.** th
164a0 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 en the value ret
164b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
164c0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
164d0 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 wid()] is.** unp
164e0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d redictable and m
164f0 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 ight not equal e
16500 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 ither the old or
16510 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 the new.** last
16520 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e insert [rowid].
16530 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 .*/.sqlite3_int6
16540 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
16550 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
16560 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
16570 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
16580 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
16590 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 Modified.**.**
165a0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 ^This function r
165b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
165c0 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f r of database ro
165d0 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 ws that were cha
165e0 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 nged.** or inser
165f0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 ted or deleted b
16600 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e y the most recen
16610 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 tly completed SQ
16620 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f L statement.** o
16630 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 n the [database
16640 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
16650 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 ified by the fir
16660 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a st parameter..**
16670 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 ^(Only changes
16680 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c that are directl
16690 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 y specified by t
166a0 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 he [INSERT], [UP
166b0 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 DATE],.** or [DE
166c0 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 LETE] statement
166d0 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 are counted. Au
166e0 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
166f0 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 caused by.** tri
16700 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 ggers or [foreig
16710 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 n key actions] a
16720 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 re not counted.)
16730 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 ^ Use the.** [sq
16740 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
16750 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 ges()] function
16760 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 to find the tota
16770 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e l number of chan
16780 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 ges.** including
16790 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 changes caused
167a0 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 by triggers and
167b0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 foreign key acti
167c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e ons..**.** ^Chan
167d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
167e0 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 at are simulated
167f0 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 by an [INSTEAD
16800 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 OF trigger].** a
16810 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 re not counted.
16820 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 Only real table
16830 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 changes are cou
16840 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 nted..**.** ^(A
16850 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 "row change" is
16860 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 a change to a si
16870 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 ngle row of a si
16880 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 ngle table.** ca
16890 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 used by an INSER
168a0 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 T, DELETE, or UP
168b0 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 DATE statement.
168c0 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 Rows that.** ar
168d0 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 e changed as sid
168e0 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 e effects of [RE
168f0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e PLACE] constrain
16900 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a t resolution,.**
16910 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 rollback, ABORT
16920 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 processing, [DR
16930 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 OP TABLE], or by
16940 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 any other.** me
16950 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 chanisms do not
16960 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 count as direct
16970 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a row changes.)^.*
16980 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 *.** A "trigger
16990 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 context" is a sc
169a0 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e ope of execution
169b0 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 that begins and
169c0 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 .** ends with th
169d0 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 e script of a [C
169e0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
169f0 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f trigger]. .** Mo
16a00 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 st SQL statement
16a10 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 s are.** evaluat
16a20 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e ed outside of an
16a30 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 y trigger. This
16a40 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 is the "top lev
16a50 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 el".** trigger c
16a60 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 ontext. If a tr
16a70 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d igger fires from
16a80 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 the top level,
16a90 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 a.** new trigger
16aa0 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 context is ente
16ab0 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 red for the dura
16ac0 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 tion of that one
16ad0 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 .** trigger. Su
16ae0 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 btriggers create
16af0 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 subcontexts for
16b00 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e their duration.
16b10 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
16b20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
16b30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 or [sqlite3_ste
16b40 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 p()] recursively
16b50 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 does.** not cre
16b60 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 ate a new trigge
16b70 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a r context..**.**
16b80 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
16b90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
16ba0 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 er of direct row
16bb0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a changes in the.
16bc0 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 ** most recent I
16bd0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
16be0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
16bf0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 nt within the sa
16c00 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f me.** trigger co
16c10 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ntext..**.** ^Th
16c20 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 us, when called
16c30 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
16c40 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f el, this functio
16c50 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a n returns the.**
16c60 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 number of chang
16c70 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 es in the most r
16c80 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 ecent INSERT, UP
16c90 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
16ca0 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 ** that also occ
16cb0 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 urred at the top
16cc0 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 level. ^(Withi
16cd0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 n the body of a
16ce0 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 trigger,.** the
16cf0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
16d00 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 ) interface can
16d10 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e be called to fin
16d20 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a d the number of.
16d30 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 ** changes in th
16d40 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
16d50 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 completed INSERT
16d60 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
16d70 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ETE.** statement
16d80 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 within the body
16d90 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 of the same tri
16da0 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 gger..** However
16db0 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 , the number ret
16dc0 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 urned does not i
16dd0 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a nclude changes.*
16de0 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 * caused by subt
16df0 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 riggers since th
16e00 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f ose have their o
16e10 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a wn context.)^.**
16e20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
16e30 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
16e40 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
16e50 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f face, the.** [co
16e60 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
16e70 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 ma], and the [ch
16e80 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
16e90 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
16ea0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
16eb0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
16ec0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
16ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
16ee0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
16ef0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 3_changes()] is
16f00 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
16f10 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
16f20 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ** is unpredicta
16f30 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
16f40 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 ingful..*/.int s
16f50 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 qlite3_changes(s
16f60 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
16f70 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c CAPI3REF: Total
16f80 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
16f90 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e Modified.**.** ^
16fa0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
16fb0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
16fc0 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 of row changes
16fd0 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 caused by [INSER
16fe0 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 T],.** [UPDATE]
16ff0 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 or [DELETE] stat
17000 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 ements since the
17010 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
17020 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 ction] was opene
17030 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e d..** ^(The coun
17040 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 t returned by sq
17050 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
17060 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 ges() includes a
17070 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 ll changes.** fr
17080 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 om all [CREATE T
17090 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
170a0 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 ] contexts and c
170b0 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a hanges made by.*
170c0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
170d0 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 ctions]. However
170e0 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 ,.** the count d
170f0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
17100 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 changes used to
17110 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 implement [REPLA
17120 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c CE] constraints,
17130 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 .** do rollbacks
17140 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 or ABORT proces
17150 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 sing, or [DROP T
17160 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 ABLE] processing
17170 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 . The.** count
17180 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
17190 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 rows of views t
171a0 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 hat fire an [INS
171b0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d TEAD OF trigger]
171c0 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 ,.** though if t
171d0 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 he INSTEAD OF tr
171e0 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e igger makes chan
171f0 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 ges of its own,
17200 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a those changes .*
17210 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e * are counted.)^
17220 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
17230 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
17240 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 function counts
17250 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 the changes as
17260 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 soon as.** the s
17270 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 tatement that ma
17280 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 kes them is comp
17290 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 leted (when the
172a0 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 statement handle
172b0 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f .** is passed to
172c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
172d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 )] or [sqlite3_f
172e0 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a inalize()])..**.
172f0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 ** See also the
17300 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
17310 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 ()] interface, t
17320 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 he.** [count_cha
17330 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e nges pragma], an
17340 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 d the [total_cha
17350 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 nges() SQL funct
17360 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
17370 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
17380 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f makes changes o
17390 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 n the same datab
173a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
173b0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 * while [sqlite3
173c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
173d0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 ] is running the
173e0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 n the value.** r
173f0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 eturned is unpre
17400 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
17410 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
17420 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 int sqlite3_tota
17430 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 l_changes(sqlite
17440 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
17450 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 3REF: Interrupt
17460 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 A Long-Running Q
17470 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 uery.**.** ^This
17480 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 function causes
17490 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 any pending dat
174a0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 abase operation
174b0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 to abort and.**
174c0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 return at its ea
174d0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 rliest opportuni
174e0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 ty. This routine
174f0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a is typically.**
17500 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f called in respo
17510 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 nse to a user ac
17520 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 tion such as pre
17530 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a ssing "Cancel".*
17540 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 * or Ctrl-C wher
17550 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 e the user wants
17560 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 a long query op
17570 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a eration to halt.
17580 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a ** immediately..
17590 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 **.** ^It is saf
175a0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
175b0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 outine from a th
175c0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 read different f
175d0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 rom the.** threa
175e0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e d that is curren
175f0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 tly running the
17600 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
17610 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 on. But it.** i
17620 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 s not safe to ca
17630 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
17640 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 with a [database
17650 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 connection] tha
17660 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f t.** is closed o
17670 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 r might close be
17680 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 fore sqlite3_int
17690 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 errupt() returns
176a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 ..**.** ^If an S
176b0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
176c0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 very nearly fini
176d0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 shed at the time
176e0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 when.** sqlite3
176f0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 _interrupt() is
17700 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 called, then it
17710 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 might not have a
17720 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a n opportunity.**
17730 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 to be interrupt
17740 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e ed and might con
17750 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 tinue to complet
17760 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 ion..**.** ^An S
17770 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 QL operation tha
17780 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 t is interrupted
17790 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
177a0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e LITE_INTERRUPT].
177b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 .** ^If the inte
177c0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 rrupted SQL oper
177d0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 ation is an INSE
177e0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 RT, UPDATE, or D
177f0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 ELETE.** that is
17800 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 inside an expli
17810 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c cit transaction,
17820 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 then the entire
17830 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 transaction.**
17840 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 will be rolled b
17850 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ack automaticall
17860 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 y..**.** ^The sq
17870 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
17880 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 D) call is in ef
17890 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 fect until all c
178a0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 urrently running
178b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
178c0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 ts on [database
178d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f connection] D co
178e0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 mplete. ^Any ne
178f0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 w SQL statements
17900 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
17910 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 rted after the s
17920 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
17930 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f () call and befo
17940 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 re the .** runni
17950 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 ng statements re
17960 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 aches zero are i
17970 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 nterrupted as if
17980 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a they had been.*
17990 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 * running prior
179a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 to the sqlite3_i
179b0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e nterrupt() call.
179c0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 ^New SQL state
179d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
179e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
179f0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 the running stat
17a00 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 ement count reac
17a10 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 hes zero are.**
17a20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 not effected by
17a30 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
17a40 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 rrupt()..** ^A c
17a50 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
17a60 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 nterrupt(D) that
17a70 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 occurs when the
17a80 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e re are no runnin
17a90 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
17aa0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 nts is a no-op a
17ab0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 nd has no effect
17ac0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e on SQL statemen
17ad0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 ts.** that are s
17ae0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 tarted after the
17af0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
17b00 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e pt() call return
17b10 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 s..**.** If the
17b20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17b30 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 ion closes while
17b40 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 [sqlite3_interr
17b50 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e upt()].** is run
17b60 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 ning then bad th
17b70 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 ings will likely
17b80 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 happen..*/.void
17b90 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
17ba0 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f pt(sqlite3*);../
17bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
17bc0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
17bd0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 QL Statement Is
17be0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 Complete.**.** T
17bf0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
17c00 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 e useful during
17c10 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 command-line inp
17c20 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ut to determine
17c30 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e if the.** curren
17c40 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 tly entered text
17c50 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 seems to form a
17c60 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
17c70 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 atement or.** if
17c80 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 additional inpu
17c90 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f t is needed befo
17ca0 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 re sending the t
17cb0 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 ext into.** SQLi
17cc0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 te for parsing.
17cd0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
17ce0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 return 1 if the
17cf0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a input string.**
17d00 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 appears to be a
17d10 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
17d20 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 atement. ^A sta
17d30 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 tement is judged
17d40 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 to be.** comple
17d50 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 te if it ends wi
17d60 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 th a semicolon t
17d70 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 oken and is not
17d80 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a a prefix of a.**
17d90 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 well-formed CRE
17da0 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 ATE TRIGGER stat
17db0 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c ement. ^Semicol
17dc0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 ons that are emb
17dd0 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 edded within.**
17de0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 string literals
17df0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 or quoted identi
17e00 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f fier names or co
17e10 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a mments are not.*
17e20 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f * independent to
17e30 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 kens (they are p
17e40 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e art of the token
17e50 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 in which they a
17e60 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 re.** embedded)
17e70 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 and thus do not
17e80 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 count as a state
17e90 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e ment terminator.
17ea0 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a ^Whitespace.**
17eb0 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 and comments th
17ec0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 at follow the fi
17ed0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 nal semicolon ar
17ee0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a e ignored..**.**
17ef0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
17f00 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 return 0 if the
17f10 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e statement is in
17f20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 complete. ^If a
17f30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
17f40 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 ation fails, the
17f50 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 n SQLITE_NOMEM i
17f60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
17f70 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
17f80 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 s do not parse t
17f90 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
17fa0 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e s thus.** will n
17fb0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 ot detect syntac
17fc0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 tically incorrec
17fd0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 t SQL..**.** ^(I
17fe0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 f SQLite has not
17ff0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 been initialize
18000 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
18010 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 _initialize()] p
18020 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f rior .** to invo
18030 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d king sqlite3_com
18040 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 plete16() then s
18050 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
18060 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
18070 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
18080 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c by sqlite3_compl
18090 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 ete16(). If tha
180a0 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e t initialization
180b0 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 fails,.** then
180c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
180d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
180e0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 mplete16() will
180f0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 be non-zero.** r
18100 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
18110 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
18120 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d input SQL is com
18130 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 plete.)^.**.** T
18140 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c he input to [sql
18150 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d ite3_complete()]
18160 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d must be a zero-
18170 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
18180 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a F-8 string..**.*
18190 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
181a0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
181b0 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 16()] must be a
181c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
181d0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
181e0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 in native byte
181f0 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 order..*/.int sq
18200 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 lite3_complete(c
18210 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b onst char *sql);
18220 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d .int sqlite3_com
18230 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f plete16(const vo
18240 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a id *sql);../*.**
18250 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 CAPI3REF: Regis
18260 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 ter A Callback T
18270 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f o Handle SQLITE_
18280 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a BUSY Errors.**.*
18290 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
182a0 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
182b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 function that mi
182c0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
182d0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
182e0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
182f0 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 open a database
18300 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 table that anot
18310 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
18320 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 process has loc
18330 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ked..**.** ^If t
18340 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
18350 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b is NULL, then [
18360 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 SQLITE_BUSY] or
18370 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c [SQLITE_IOERR_BL
18380 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 OCKED].** is ret
18390 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
183a0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 y upon encounter
183b0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e ing the lock. ^
183c0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
183d0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e back.** is not N
183e0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 ULL, then the ca
183f0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 llback might be
18400 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f invoked with two
18410 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
18420 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
18430 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 ument to the bus
18440 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 y handler is a c
18450 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
18460 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
18470 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
18480 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
18490 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
184a0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ). ^The second
184b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
184c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
184d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
184e0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
184f0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
18500 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
18510 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 n invoked for th
18520 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 is locking event
18530 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 . ^If the.** bu
18540 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
18550 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
18560 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
18570 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
18580 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
18590 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
185a0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
185b0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
185c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a ] is returned..*
185d0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 * ^If the callba
185e0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
185f0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 ero, then anothe
18600 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 r attempt.** is
18610 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 made to open the
18620 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 database for re
18630 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 ading and the cy
18640 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a cle repeats..**.
18650 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 ** The presence
18660 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 of a busy handle
18670 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 r does not guara
18680 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c ntee that it wil
18690 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 l be invoked.**
186a0 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f when there is lo
186b0 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e ck contention. ^
186c0 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d If SQLite determ
186d0 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 ines that invoki
186e0 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 ng the busy.** h
186f0 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 andler could res
18700 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 ult in a deadloc
18710 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 k, it will go ah
18720 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b ead and return [
18730 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 SQLITE_BUSY].**
18740 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
18750 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 _BLOCKED] instea
18760 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 d of invoking th
18770 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
18780 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 ** Consider a sc
18790 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 enario where one
187a0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
187b0 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 ing a read lock
187c0 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 that.** it is tr
187d0 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 ying to promote
187e0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f to a reserved lo
187f0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f ck and.** a seco
18800 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f nd process is ho
18810 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 lding a reserved
18820 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 lock that it is
18830 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 trying.** to pr
18840 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c omote to an excl
18850 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 usive lock. The
18860 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 first process c
18870 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a annot proceed.**
18880 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 because it is b
18890 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 locked by the se
188a0 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 cond and the sec
188b0 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e ond process cann
188c0 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 ot.** proceed be
188d0 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 cause it is bloc
188e0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ked by the first
188f0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 . If both proce
18900 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 sses.** invoke t
18910 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 he busy handlers
18920 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d , neither will m
18930 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 ake any progress
18940 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a . Therefore,.**
18950 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 SQLite returns
18960 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f [SQLITE_BUSY] fo
18970 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 r the first proc
18980 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 ess, hoping that
18990 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e this.** will in
189a0 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 duce the first p
189b0 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 rocess to releas
189c0 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 e its read lock
189d0 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 and allow.** the
189e0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
189f0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a to proceed..**.*
18a00 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
18a10 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
18a20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
18a30 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 [SQLITE_BUSY] e
18a40 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 rror is converte
18a50 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 d to [SQLITE_IOE
18a60 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 RR_BLOCKED].** w
18a70 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e hen SQLite is in
18a80 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 the middle of a
18a90 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 large transacti
18aa0 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 on where all the
18ab0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c .** changes will
18ac0 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 not fit into th
18ad0 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 e in-memory cach
18ae0 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a e. SQLite will.
18af0 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 ** already hold
18b00 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 a RESERVED lock
18b10 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 on the database
18b20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 file, but it nee
18b30 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 ds.** to promote
18b40 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 this lock to EX
18b50 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 CLUSIVE so that
18b60 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 it can spill cac
18b70 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f he.** pages into
18b80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
18b90 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 le without harm
18ba0 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a to concurrent.**
18bb0 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 readers. ^If i
18bc0 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 t is unable to p
18bd0 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c romote the lock,
18be0 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d then the in-mem
18bf0 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c ory.** cache wil
18c00 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 l be left in an
18c10 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 inconsistent sta
18c20 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 te and so the er
18c30 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 ror.** code is p
18c40 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 romoted from the
18c50 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 relatively beni
18c60 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d gn [SQLITE_BUSY]
18c70 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 to.** the more
18c80 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 severe [SQLITE_I
18c90 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 OERR_BLOCKED].
18ca0 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 ^This error code
18cb0 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f promotion.** fo
18cc0 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 rces an automati
18cd0 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 c rollback of th
18ce0 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 e changes. See
18cf0 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 the.** <a href="
18d00 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d /cvstrac/wiki?p=
18d10 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 CorruptionFollow
18d20 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a ingBusyError">.*
18d30 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c * CorruptionFoll
18d40 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f owingBusyError</
18d50 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 a> wiki page for
18d60 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 a discussion of
18d70 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 why.** this is
18d80 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a important..**.**
18d90 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
18da0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
18db0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e sy handler defin
18dc0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b ed for each.** [
18dd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18de0 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 ion]. Setting a
18df0 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 new busy handle
18e00 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 r clears any.**
18e10 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 previously set h
18e20 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 andler.)^ ^Note
18e30 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 that calling [s
18e40 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
18e50 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 out()].** will a
18e60 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 lso set or clear
18e70 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
18e80 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 r..**.** The bus
18e90 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c y callback shoul
18ea0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 d not take any a
18eb0 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 ctions which mod
18ec0 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ify the.** datab
18ed0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
18ee0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
18ef0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 busy handler. A
18f00 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a ny such actions.
18f10 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 ** result in und
18f20 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
18f30 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 .** .** A busy h
18f40 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
18f50 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
18f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
18f70 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
18f80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
18f90 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
18fa0 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 andler..*/.int s
18fb0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
18fc0 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
18fd0 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c t(*)(void*,int),
18fe0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
18ff0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
19000 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a Busy Timeout.**.
19010 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
19020 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
19030 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
19040 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
19050 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
19060 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
19070 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
19080 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
19090 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 ed. ^The handle
190a0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
190b0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
190c0 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
190d0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
190e0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
190f0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
19100 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 ^After at leas
19110 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
19120 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c nds of sleeping,
19130 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
19140 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 returns 0 which
19150 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f causes [sqlite3_
19160 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 step()] to retur
19170 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 n.** [SQLITE_BUS
19180 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f Y] or [SQLITE_IO
19190 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a ERR_BLOCKED]..**
191a0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 .** ^Calling thi
191b0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
191c0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
191d0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
191e0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
191f0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
19200 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lers..**.** ^(Th
19210 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
19220 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
19230 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
19240 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
19250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
19260 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
19270 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
19280 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
19290 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
192a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
192b0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
192c0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
192d0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
192e0 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
192f0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
19300 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 ared.)^.*/.int s
19310 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
19320 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
19330 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
19340 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
19350 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
19360 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
19370 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 .**.** This is a
19380 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
19390 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 e that is preser
193a0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ved for backward
193b0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
193c0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 .** Use of this
193d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
193e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a recommended..**
193f0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 .** Definition:
19400 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c A <b>result tabl
19410 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 e</b> is memory
19420 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 data structure c
19430 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a reated by the.**
19440 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
19450 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ble()] interface
19460 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c . A result tabl
19470 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a e records the.**
19480 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 complete query
19490 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 results from one
194a0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 or more queries
194b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c ..**.** The tabl
194c0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 e conceptually h
194d0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 as a number of r
194e0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e ows and columns.
194f0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e But.** these n
19500 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 umbers are not p
19510 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c art of the resul
19520 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 t table itself.
19530 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 These.** number
19540 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 s are obtained s
19550 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 eparately. Let
19560 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 N be the number
19570 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d of rows.** and M
19580 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
19590 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a f columns..**.**
195a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
195b0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
195c0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d ointers to zero-
195d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
195e0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
195f0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 re are (N+1)*M e
19600 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 lements in the a
19610 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 rray. The first
19620 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
19630 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 t.** to zero-ter
19640 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
19650 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 that contain th
19660 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
19670 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
19680 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
19690 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
196a0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
196b0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 LL values result
196c0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e .** in NULL poin
196d0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 ters. All other
196e0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 values are in t
196f0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d heir UTF-8 zero-
19700 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
19710 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
19720 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
19730 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
19740 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
19750 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
19760 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f might consist o
19770 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 f one or more me
19780 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
19790 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 ..** It is not s
197a0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 afe to pass a re
197b0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 sult table direc
197c0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f tly to [sqlite3_
197d0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 free()]..** A re
197e0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c sult table shoul
197f0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 d be deallocated
19800 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
19810 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
19820 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 *.** ^(As an exa
19830 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
19840 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
19850 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
19860 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
19870 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
19880 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
19890 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
198a0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
198b0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
198c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
198d0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
198e0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
198f0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
19900 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
19910 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
19920 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
19930 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
19940 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
19950 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
19960 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
19970 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
19980 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
19990 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
199a0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
199b0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
199c0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
199d0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
199e0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
199f0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
19a00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
19a10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
19a20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
19a30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
19a40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
19a50 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
19a60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
19a70 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
19a80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
19a90 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
19aa0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
19ab0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
19ac0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
19ad0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
19ae0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
19af0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
19b00 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
19b10 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
19b20 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
19b30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
19b40 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
19b50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^The sqlite3_ge
19b60 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 t_table() functi
19b70 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 on evaluates one
19b80 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 or more.** semi
19b90 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 colon-separated
19ba0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
19bb0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 n the zero-termi
19bc0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 nated UTF-8.** s
19bd0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 tring of its 2nd
19be0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 parameter and r
19bf0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
19c00 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
19c10 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
19c20 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
19c30 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
19c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
19c50 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
19c60 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f h the result fro
19c70 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 m sqlite3_get_ta
19c80 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 ble(),.** it mus
19c90 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c t pass the resul
19ca0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 t table pointer
19cb0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f to sqlite3_free_
19cc0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 table() in order
19cd0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 to.** release t
19ce0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 he memory that w
19cf0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 as malloced. Be
19d00 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
19d10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
19d20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 _malloc()] happe
19d30 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 ns within sqlite
19d40 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 3_get_table(), t
19d50 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 he calling.** fu
19d60 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
19d70 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c try to call [sql
19d80 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 ite3_free()] dir
19d90 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ectly. Only.**
19da0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
19db0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
19dc0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 o release the me
19dd0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
19de0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
19df0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
19e00 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 table() interfac
19e10 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 e is implemented
19e20 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 as a wrapper ar
19e30 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
19e40 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 _exec()]. The s
19e50 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
19e60 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
19e70 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a not have access.
19e80 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e ** to any intern
19e90 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 al data structur
19ea0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 es of SQLite. I
19eb0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 t uses only the
19ec0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 public.** interf
19ed0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 ace defined here
19ee0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 . As a conseque
19ef0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 nce, errors that
19f00 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a occur in the.**
19f10 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f wrapper layer o
19f20 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e utside of the in
19f30 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f ternal [sqlite3_
19f40 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 exec()] call are
19f50 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 not.** reflecte
19f60 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 d in subsequent
19f70 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
19f80 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 3_errcode()] or.
19f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
19fa0 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 sg()]..*/.int sq
19fb0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
19fc0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
19fd0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f /* An o
19fe0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a pen database */.
19ff0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
1a000 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 ql, /* SQL t
1a010 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
1a020 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 /. char ***pazR
1a030 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 esult, /* Res
1a040 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 ults of the quer
1a050 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f y */. int *pnRo
1a060 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 w, /*
1a070 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
1a080 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 rows written he
1a090 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 re */. int *pnC
1a0a0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a olumn, /*
1a0b0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
1a0c0 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 t columns writte
1a0d0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 n here */. char
1a0e0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 **pzErrmsg
1a0f0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 /* Error msg w
1a100 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 ritten here */.)
1a110 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 ;.void sqlite3_f
1a120 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a ree_table(char *
1a130 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a *result);../*.**
1a140 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 CAPI3REF: Forma
1a150 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e tted String Prin
1a160 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ting Functions.*
1a170 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1a180 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 nes are work-ali
1a190 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e kes of the "prin
1a1a0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 tf()" family of
1a1b0 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f functions.** fro
1a1c0 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
1a1d0 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 library..**.**
1a1e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 ^The sqlite3_mpr
1a1f0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 intf() and sqlit
1a200 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f e3_vmprintf() ro
1a210 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 utines write the
1a220 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e ir.** results in
1a230 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
1a240 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
1a250 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 _malloc()]..** T
1a260 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 he strings retur
1a270 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f ned by these two
1a280 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 routines should
1a290 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 be.** released
1a2a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 by [sqlite3_free
1a2b0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 ()]. ^Both rout
1a2c0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a ines return a.**
1a2d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 NULL pointer if
1a2e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1a2f0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ()] is unable to
1a300 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 allocate enough
1a310 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f .** memory to ho
1a320 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 ld the resulting
1a330 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e string..**.** ^
1a340 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 (The sqlite3_snp
1a350 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
1a360 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 is similar to "s
1a370 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a nprintf()" from.
1a380 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 ** the standard
1a390 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 C library. The
1a3a0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 result is writte
1a3b0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 n into the.** bu
1a3c0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 ffer supplied as
1a3d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1a3e0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 meter whose size
1a3f0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 is given by.**
1a400 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1a410 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 ter. Note that t
1a420 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a he order of the.
1a430 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 ** first two par
1a440 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 ameters is rever
1a450 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 sed from snprint
1a460 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 f().)^ This is
1a470 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c an.** historical
1a480 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 accident that c
1a490 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 annot be fixed w
1a4a0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a ithout breaking.
1a4b0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
1a4c0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e patibility. ^(N
1a4d0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 ote also that sq
1a4e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1a4f0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f .** returns a po
1a500 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 inter to its buf
1a510 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 fer instead of t
1a520 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
1a530 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 characters actua
1a540 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f lly written into
1a550 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 the buffer.)^
1a560 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a We admit that.**
1a570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
1a580 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 haracters writte
1a590 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 n would be a mor
1a5a0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a e useful return.
1a5b0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 ** value but we
1a5c0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 cannot change th
1a5d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1a5e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 of sqlite3_snpr
1a5f0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 intf().** now wi
1a600 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 thout breaking c
1a610 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
1a620 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 .** ^As long as
1a630 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 the buffer size
1a640 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 is greater than
1a650 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e zero, sqlite3_sn
1a660 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 printf().** guar
1a670 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 antees that the
1a680 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 buffer is always
1a690 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1a6a0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a . ^The first.**
1a6b0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 parameter "n" i
1a6c0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 s the total size
1a6d0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 of the buffer,
1a6e0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 including space
1a6f0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 for.** the zero
1a700 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 terminator. So
1a710 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 the longest stri
1a720 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 ng that can be c
1a730 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 ompletely.** wri
1a740 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 tten will be n-1
1a750 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
1a760 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1a770 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 vsnprintf() rout
1a780 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 ine is a varargs
1a790 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 version of sqli
1a7a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a te3_snprintf()..
1a7b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1a7c0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 ines all impleme
1a7d0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e nt some addition
1a7e0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a al formatting.**
1a7f0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 options that ar
1a800 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e e useful for con
1a810 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 structing SQL st
1a820 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c atements..** All
1a830 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 of the usual pr
1a840 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e intf() formattin
1a850 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e g options apply.
1a860 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 In addition, t
1a870 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 here.** is are "
1a880 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 %q", "%Q", and "
1a890 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
1a8a0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
1a8b0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
1a8c0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
1a8d0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 titutes a nul-te
1a8e0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
1a8f0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
1a900 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
1a910 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
1a920 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
1a930 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
1a940 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
1a950 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
1a960 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 literal.)^ By d
1a970 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
1a980 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
1a990 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
1a9a0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
1a9b0 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
1a9c0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
1a9d0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
1a9e0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 For example, ass
1a9f0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 ume the string v
1aa00 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f ariable zText co
1aa10 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 ntains text as f
1aa20 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1aa30 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1aa40 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 ** char *zText
1aa50 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 = "It's a happy
1aa60 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e day!";.** </pre>
1aa70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1aa80 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 .** One can use
1aa90 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 this text in an
1aaa0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
1aab0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1aac0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1aad0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1aae0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1aaf0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1ab00 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 table VALUES('%q
1ab10 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 ')", zText);.**
1ab20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1ab30 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1ab40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1ab50 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1ab60 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1ab70 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
1ab80 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 he %q format str
1ab90 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
1aba0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 '\'' character
1abb0 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 in zText.** is e
1abc0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 scaped and the S
1abd0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 QL generated is
1abe0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1abf0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1ac00 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1ac10 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1ac20 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 S('It''s a happy
1ac30 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 day!').** </pre
1ac40 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1ac50 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 *.** This is cor
1ac60 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 rect. Had we us
1ac70 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 ed %s instead of
1ac80 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 %q, the generat
1ac90 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 ed SQL.** would
1aca0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 have looked like
1acb0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c this:.**.** <bl
1acc0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1acd0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 * INSERT INTO t
1ace0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 able1 VALUES('It
1acf0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
1ad00 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1ad10 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1ad20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d This second exam
1ad30 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 ple is an SQL sy
1ad40 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 ntax error. As
1ad50 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 a general rule y
1ad60 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 ou should.** alw
1ad70 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 ays use %q inste
1ad80 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e ad of %s when in
1ad90 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 serting text int
1ada0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 o a string liter
1adb0 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 al..**.** ^(The
1adc0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
1add0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
1ade0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
1adf0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
1ae00 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
1ae10 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
1ae20 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
1ae30 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
1ae40 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
1ae50 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
1ae60 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
1ae70 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
1ae80 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
1ae90 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
1aea0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f e quotes).)^ So
1aeb0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f , for example, o
1aec0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a ne could say:.**
1aed0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1aee0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1aef0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
1af00 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
1af10 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
1af20 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a (%Q)", zText);.*
1af30 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
1af40 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
1af50 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
1af60 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
1af70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1af80 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 e>.**.** The cod
1af90 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e e above will ren
1afa0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 der a correct SQ
1afb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 L statement in t
1afc0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 he zSQL.** varia
1afd0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 ble even if the
1afe0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 zText variable i
1aff0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1b000 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 ..**.** ^(The "%
1b010 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 z" formatting op
1b020 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
1b030 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 "%s" but with th
1b040 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 e.** addition th
1b050 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 at after the str
1b060 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 ing has been rea
1b070 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 d and copied int
1b080 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c o.** the result,
1b090 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1b0a0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 ] is called on t
1b0b0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e he input string.
1b0c0 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 )^.*/.char *sqli
1b0d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
1b0e0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 t char*,...);.ch
1b0f0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 ar *sqlite3_vmpr
1b100 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
1b110 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 , va_list);.char
1b120 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e *sqlite3_snprin
1b130 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e tf(int,char*,con
1b140 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a st char*, ...);.
1b150 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 char *sqlite3_vs
1b160 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
1b170 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 *,const char*, v
1b180 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 a_list);../*.**
1b190 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
1b1a0 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 Allocation Subs
1b1b0 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ystem.**.** The
1b1c0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 SQLite core uses
1b1d0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 these three rou
1b1e0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 tines for all of
1b1f0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 its own.** inte
1b200 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rnal memory allo
1b210 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 cation needs. "C
1b220 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 ore" in the prev
1b230 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a ious sentence.**
1b240 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
1b250 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 e operating-syst
1b260 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 em specific VFS
1b270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
1b280 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 The.** Windows
1b290 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 VFS uses native
1b2a0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
1b2b0 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 e() for some ope
1b2c0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e rations..**.** ^
1b2d0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c The sqlite3_mall
1b2e0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 oc() routine ret
1b2f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1b300 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 o a block.** of
1b310 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 memory at least
1b320 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 N bytes in lengt
1b330 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 h, where N is th
1b340 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 e parameter..**
1b350 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ^If sqlite3_mall
1b360 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 oc() is unable t
1b370 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 o obtain suffici
1b380 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f ent free.** memo
1b390 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 ry, it returns a
1b3a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
1b3b0 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 ^If the paramete
1b3c0 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 r N to.** sqlite
1b3d0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 3_malloc() is ze
1b3e0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 ro or negative t
1b3f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c hen sqlite3_mall
1b400 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 oc() returns.**
1b410 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
1b420 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
1b430 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
1b440 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
1b450 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
1b460 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
1b470 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1b480 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
1b490 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
1b4a0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
1b4b0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
1b4c0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 ^The sqlite3_f
1b4d0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
1b4e0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
1b4f0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1b500 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
1b510 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
1b520 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
1b530 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
1b540 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
1b550 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
1b560 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
1b570 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
1b580 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
1b590 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
1b5a0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
1b5b0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
1b5c0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
1b5d0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
1b5e0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
1b5f0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
1b600 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
1b610 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
1b620 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1b630 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
1b640 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
1b650 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
1b660 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
1b670 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
1b680 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
1b690 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1b6a0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1b6b0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 ealloc()..**.**
1b6c0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^(The sqlite3_re
1b6d0 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 alloc() interfac
1b6e0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 e attempts to re
1b6f0 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 size a.** prior
1b700 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1b710 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 n to be at least
1b720 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 N bytes, where
1b730 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f N is the.** seco
1b740 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 nd parameter. T
1b750 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
1b760 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a tion to be resiz
1b770 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a ed is the first.
1b780 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 ** parameter.)^
1b790 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 ^ If the first p
1b7a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1b7b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a te3_realloc().**
1b7c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1b7d0 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 er then its beha
1b7e0 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 vior is identica
1b7f0 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 l to calling.**
1b800 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
1b810 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 ) where N is the
1b820 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1b830 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
1b840 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 lloc()..** ^If t
1b850 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1b860 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
1b870 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f ealloc() is zero
1b880 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 or.** negative
1b890 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
1b8a0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 r is exactly the
1b8b0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 same as calling
1b8c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
1b8d0 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 (P) where P is t
1b8e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1b8f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1b900 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c alloc()..** ^sql
1b910 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
1b920 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1b930 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c to a memory all
1b940 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 ocation.** of at
1b950 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
1b960 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 n size or NULL i
1b970 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d f sufficient mem
1b980 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 ory is unavailab
1b990 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 le..** ^If M is
1b9a0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
1b9b0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1b9c0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 , then min(N,M)
1b9d0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 bytes.** of the
1b9e0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1b9f0 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f are copied into
1ba00 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
1ba10 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 f buffer returne
1ba20 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
1ba30 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 realloc() and th
1ba40 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1ba50 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
1ba60 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
1ba70 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 loc() returns NU
1ba80 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 LL, then the pri
1ba90 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a or allocation.**
1baa0 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a is not freed..*
1bab0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 *.** ^The memory
1bac0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
1bad0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e ite3_malloc() an
1bae0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f d sqlite3_reallo
1baf0 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 c().** is always
1bb00 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c aligned to at l
1bb10 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 east an 8 byte b
1bb20 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 oundary, or to a
1bb30 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 .** 4 byte bound
1bb40 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 ary if the [SQLI
1bb50 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 TE_4_BYTE_ALIGNE
1bb60 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c D_MALLOC] compil
1bb70 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
1bb80 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
1bb90 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f In SQLite versio
1bba0 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e n 3.5.0 and 3.5.
1bbb0 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 1, it was possib
1bbc0 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 le to define.**
1bbd0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f the SQLITE_OMIT_
1bbe0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f MEMORY_ALLOCATIO
1bbf0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 N which would ca
1bc00 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e use the built-in
1bc10 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
1bc20 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 on of these rout
1bc30 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 ines to be omitt
1bc40 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 ed. That capabi
1bc50 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f lity.** is no lo
1bc60 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 nger provided.
1bc70 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 Only built-in me
1bc80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 mory allocators
1bc90 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a can be used..**.
1bca0 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 ** Prior to SQLi
1bcb0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 te version 3.7.1
1bcc0 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 0, the Windows O
1bcd0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
1bce0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 r called.** the
1bcf0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
1bd00 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 and free() direc
1bd10 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 tly when convert
1bd20 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 ing.** filenames
1bd30 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 between the UTF
1bd40 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 -8 encoding used
1bd50 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e by SQLite.** an
1bd60 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e d whatever filen
1bd70 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ame encoding is
1bd80 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 used by the part
1bd90 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a icular Windows.*
1bda0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 * installation.
1bdb0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
1bdc0 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 on errors were d
1bdd0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 etected, but.**
1bde0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 they were report
1bdf0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 ed back as [SQLI
1be00 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a TE_CANTOPEN] or.
1be10 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
1be20 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 ] rather than [S
1be30 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
1be40 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 .** The pointer
1be50 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 arguments to [sq
1be60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e lite3_free()] an
1be70 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
1be80 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 oc()].** must be
1be90 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 either NULL or
1bea0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 else pointers ob
1beb0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 tained from a pr
1bec0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ior.** invocatio
1bed0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
1bee0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
1bef0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 te3_realloc()] t
1bf00 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 hat have.** not
1bf10 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 yet been release
1bf20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 d..**.** The app
1bf30 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
1bf40 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 t read or write
1bf50 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 any part of.** a
1bf60 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 block of memory
1bf70 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
1bf80 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e en released usin
1bf90 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 g.** [sqlite3_fr
1bfa0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ee()] or [sqlite
1bfb0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 3_realloc()]..*/
1bfc0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d .void *sqlite3_m
1bfd0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 alloc(int);.void
1bfe0 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f *sqlite3_reallo
1bff0 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 c(void*, int);.v
1c000 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
1c010 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 (void*);../*.**
1c020 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
1c030 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 Allocator Stati
1c040 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 stics.**.** SQLi
1c050 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 te provides thes
1c060 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 e two interfaces
1c070 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f for reporting o
1c080 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 n the status.**
1c090 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
1c0a0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 malloc()], [sqli
1c0b0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 te3_free()], and
1c0c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
1c0d0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 c()].** routines
1c0e0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 , which form the
1c0f0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1c100 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
1c110 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ystem..**.** ^Th
1c120 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 e [sqlite3_memor
1c130 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e y_used()] routin
1c140 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
1c150 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a mber of bytes.**
1c160 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 of memory curre
1c170 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 ntly outstanding
1c180 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e (malloced but n
1c190 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 ot freed)..** ^T
1c1a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
1c1b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1c1c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1c1d0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 the maximum.** v
1c1e0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 alue of [sqlite3
1c1f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1c200 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 since the high-w
1c210 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 ater mark.** was
1c220 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 last reset. ^T
1c230 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
1c240 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ed by [sqlite3_m
1c250 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e emory_used()] an
1c260 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 d.** [sqlite3_me
1c270 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
1c280 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 ] include any ov
1c290 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 erhead.** added
1c2a0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 by SQLite in its
1c2b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1c2c0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c of [sqlite3_mall
1c2d0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f oc()],.** but no
1c2e0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 t overhead added
1c2f0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 by the any unde
1c300 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 rlying system li
1c310 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 brary.** routine
1c320 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f s that [sqlite3_
1c330 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 malloc()] may ca
1c340 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ll..**.** ^The m
1c350 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 emory high-water
1c360 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 mark is reset t
1c370 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 o the current va
1c380 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 lue of.** [sqlit
1c390 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1c3a0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
1c3b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 the parameter t
1c3c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 o.** [sqlite3_me
1c3d0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
1c3e0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 ] is true. ^The
1c3f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
1c400 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ** by [sqlite3_m
1c410 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1c420 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 1)] is the high-
1c430 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 water mark.** pr
1c440 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 ior to the reset
1c450 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ..*/.sqlite3_int
1c460 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
1c470 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 y_used(void);.sq
1c480 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
1c490 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1c4a0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c ater(int resetFl
1c4b0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ag);../*.** CAPI
1c4c0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 3REF: Pseudo-Ran
1c4d0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 dom Number Gener
1c4e0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ator.**.** SQLit
1c4f0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 e contains a hig
1c500 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f h-quality pseudo
1c510 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 -random number g
1c520 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 enerator (PRNG)
1c530 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 used to.** selec
1c540 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 t random [ROWID
1c550 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 | ROWIDs] when i
1c560 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 nserting new rec
1c570 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c ords into a tabl
1c580 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 e that.** alread
1c590 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 y uses the large
1c5a0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 st possible [ROW
1c5b0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 ID]. The PRNG i
1c5c0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a s also used for.
1c5d0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 ** the build-in
1c5e0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e random() and ran
1c5f0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 domblob() SQL fu
1c600 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 nctions. This i
1c610 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a nterface allows.
1c620 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
1c630 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 to access the sa
1c640 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 me PRNG for othe
1c650 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a r purposes..**.*
1c660 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 * ^A call to thi
1c670 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
1c680 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 N bytes of rand
1c690 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 omness into buff
1c6a0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 er P..**.** ^The
1c6b0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 first time this
1c6c0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f routine is invo
1c6d0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 ked (either inte
1c6e0 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 rnally or by.**
1c6f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 the application)
1c700 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 the PRNG is see
1c710 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d ded using random
1c720 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a ness obtained.**
1c730 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f from the xRando
1c740 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 mness method of
1c750 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
1c760 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
1c770 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 ..** ^On all sub
1c780 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 sequent invocati
1c790 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d ons, the pseudo-
1c7a0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 randomness is ge
1c7b0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 nerated.** inter
1c7c0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 nally and withou
1c7d0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 t recourse to th
1c7e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 e [sqlite3_vfs]
1c7f0 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d xRandomness.** m
1c800 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 ethod..*/.void s
1c810 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
1c820 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 s(int N, void *P
1c830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1c840 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
1c850 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 Authorization C
1c860 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
1c870 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 This routine reg
1c880 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 isters an author
1c890 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 izer callback wi
1c8a0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a th a particular.
1c8b0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1c8c0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 nection], suppli
1c8d0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
1c8e0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 argument..** ^Th
1c8f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1c900 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
1c910 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e as SQL statemen
1c920 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d ts are being com
1c930 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c piled.** by [sql
1c940 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
1c950 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 or its variants
1c960 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1c970 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 _v2()],.** [sqli
1c980 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
1c990 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
1c9a0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 epare16_v2()].
1c9b0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 ^At various.** p
1c9c0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 oints during the
1c9d0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f compilation pro
1c9e0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 cess, as logic i
1c9f0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a s being created.
1ca00 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 ** to perform va
1ca10 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 rious actions, t
1ca20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1ca30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1ca40 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 d to.** see if t
1ca50 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 hose actions are
1ca60 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 allowed. ^The
1ca70 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1ca80 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ack should.** re
1ca90 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
1caa0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 to allow the ac
1cab0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 tion, [SQLITE_IG
1cac0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f NORE] to disallo
1cad0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 w the.** specifi
1cae0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c c action but all
1caf0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ow the SQL state
1cb00 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 ment to continue
1cb10 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c to be.** compil
1cb20 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 ed, or [SQLITE_D
1cb30 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 ENY] to cause th
1cb40 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 e entire SQL sta
1cb50 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 tement to be.**
1cb60 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e rejected with an
1cb70 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 error. ^If the
1cb80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1cb90 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
1cba0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 any value other
1cbb0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e than [SQLITE_IGN
1cbc0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b ORE], [SQLITE_OK
1cbd0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 ], or [SQLITE_DE
1cbe0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 NY].** then the
1cbf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1cc00 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
1cc10 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
1cc20 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 riggered.** the
1cc30 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
1cc40 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
1cc50 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a or message..**.*
1cc60 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 * When the callb
1cc70 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1cc80 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 ITE_OK], that me
1cc90 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f ans the operatio
1cca0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 n.** requested i
1ccb0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 s ok. ^When the
1ccc0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1ccd0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c s [SQLITE_DENY],
1cce0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1ccf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
1cd00 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
1cd10 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
1cd20 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
1cd30 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
1cd40 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
1cd50 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 ge explaining th
1cd60 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 at.** access is
1cd70 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e denied. .**.** ^
1cd80 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
1cd90 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
1cda0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1cdb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
1cdc0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 third.** paramet
1cdd0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
1cde0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1cdf0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 () interface. ^T
1ce00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1ce10 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ter.** to the ca
1ce20 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
1ce30 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 eger [SQLITE_COP
1ce40 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d Y | action code]
1ce50 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a that specifies.
1ce60 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 ** the particula
1ce70 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 r action to be a
1ce80 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 uthorized. ^The
1ce90 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 third through si
1cea0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a xth parameters.*
1ceb0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
1cec0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 k are zero-termi
1ced0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
1cee0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 at contain addit
1cef0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 ional.** details
1cf00 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f about the actio
1cf10 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
1cf20 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
1cf30 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 e action code is
1cf40 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a [SQLITE_READ].*
1cf50 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 * and the callba
1cf60 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
1cf70 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
1cf80 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
1cf90 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 statement] stat
1cfa0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 ement is constru
1cfb0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 cted to substitu
1cfc0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c te.** a NULL val
1cfd0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 ue in place of t
1cfe0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 he table column
1cff0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a that would have.
1d000 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 ** been read if
1d010 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 [SQLITE_OK] had
1d020 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 been returned.
1d030 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f The [SQLITE_IGNO
1d040 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 RE].** return ca
1d050 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e n be used to den
1d060 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 y an untrusted u
1d070 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e ser access to in
1d080 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 dividual.** colu
1d090 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a mns of a table..
1d0a0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
1d0b0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
1d0c0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 E_DELETE] and th
1d0d0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
1d0e0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 ns.** [SQLITE_IG
1d0f0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b NORE] then the [
1d100 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f DELETE] operatio
1d110 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 n proceeds but t
1d120 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 he.** [truncate
1d130 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 optimization] is
1d140 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c disabled and al
1d150 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 l rows are delet
1d160 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e ed individually.
1d170 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 .**.** An author
1d180 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 izer is used whe
1d190 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 n [sqlite3_prepa
1d1a0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a re | preparing].
1d1b0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
1d1c0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 s from an untrus
1d1d0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 ted source, to e
1d1e0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 nsure that the S
1d1f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
1d200 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 do not try to a
1d210 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 ccess data they
1d220 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 are not allowed
1d230 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 to see, or that
1d240 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 they do not.** t
1d250 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 ry to execute ma
1d260 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e licious statemen
1d270 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 ts that damage t
1d280 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f he database. Fo
1d290 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e r.** example, an
1d2a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
1d2b0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f allow a user to
1d2c0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 enter arbitrary
1d2d0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 .** SQL queries
1d2e0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 for evaluation b
1d2f0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 y a database. B
1d300 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ut the applicati
1d310 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 on does.** not w
1d320 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 ant the user to
1d330 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 be able to make
1d340 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 arbitrary change
1d350 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 s to the.** data
1d360 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 base. An author
1d370 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 izer could then
1d380 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 be put in place
1d390 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 while the.** use
1d3a0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 r-entered SQL is
1d3b0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f being [sqlite3_
1d3c0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
1d3d0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 ed] that.** disa
1d3e0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 llows everything
1d3f0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d except [SELECT]
1d400 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
1d410 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
1d420 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f that need to pro
1d430 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e cess SQL from un
1d440 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a trusted sources.
1d450 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f ** might also co
1d460 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 nsider lowering
1d470 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 resource limits
1d480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c using [sqlite3_l
1d490 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c imit()].** and l
1d4a0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 imiting database
1d4b0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 size using the
1d4c0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
1d4d0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 [PRAGMA].** in
1d4e0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e addition to usin
1d4f0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e g an authorizer.
1d500 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 .**.** ^(Only a
1d510 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 single authorize
1d520 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 r can be in plac
1d530 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 e on a database
1d540 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 connection.** at
1d550 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 a time. Each c
1d560 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
1d570 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 et_authorizer ov
1d580 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 errides the.** p
1d590 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 revious call.)^
1d5a0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 ^Disable the au
1d5b0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 thorizer by inst
1d5c0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 alling a NULL ca
1d5d0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 llback..** The a
1d5e0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 uthorizer is dis
1d5f0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
1d600 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 ..**.** The auth
1d610 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1d620 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
1d630 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
1d640 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
1d650 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1d660 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
1d670 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1d680 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 lback..** Note t
1d690 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hat [sqlite3_pre
1d6a0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b pare_v2()] and [
1d6b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1d6c0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 both modify thei
1d6d0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
1d6e0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 nnections for th
1d6f0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f e meaning of "mo
1d700 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 dify" in this pa
1d710 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e ragraph..**.** ^
1d720 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 When [sqlite3_pr
1d730 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 epare_v2()] is u
1d740 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 sed to prepare a
1d750 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a statement, the.
1d760 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 ** statement mig
1d770 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 ht be re-prepare
1d780 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 d during [sqlite
1d790 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 3_step()] due to
1d7a0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 a .** schema ch
1d7b0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 ange. Hence, th
1d7c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
1d7d0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 ould ensure that
1d7e0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 the.** correct
1d7f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1d800 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 ack remains in p
1d810 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 lace during the
1d820 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1d830 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 ..**.** ^Note th
1d840 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 at the authorize
1d850 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
1d860 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e voked only durin
1d870 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 g.** [sqlite3_pr
1d880 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
1d890 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f variants. Autho
1d8a0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a rization is not.
1d8b0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 ** performed dur
1d8c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 ing statement ev
1d8d0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c aluation in [sql
1d8e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e ite3_step()], un
1d8f0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 less.** as state
1d900 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 d in the previou
1d910 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c s paragraph, sql
1d920 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f ite3_step() invo
1d930 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 kes.** sqlite3_p
1d940 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 repare_v2() to r
1d950 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 eprepare a state
1d960 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 ment after a sch
1d970 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 ema change..*/.i
1d980 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 nt sqlite3_set_a
1d990 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c uthorizer(. sql
1d9a0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 ite3*,. int (*x
1d9b0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c Auth)(void*,int,
1d9c0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1d9d0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1d9e0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 ar*,const char*)
1d9f0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 ,. void *pUserD
1da00 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ata.);../*.** CA
1da10 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1da20 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a er Return Codes.
1da30 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
1da40 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1da50 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 r | authorizer c
1da60 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1da70 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e ] must.** return
1da80 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
1da90 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 OK] or one of th
1daa0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 ese two constant
1dab0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f s in order.** to
1dac0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 signal SQLite w
1dad0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
1dae0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d e action is perm
1daf0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a itted. See the.
1db00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f ** [sqlite3_set_
1db10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 authorizer | aut
1db20 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 horizer document
1db30 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 ation] for addit
1db40 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
1db50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 tion..**.** Note
1db60 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e that SQLITE_IGN
1db70 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 ORE is also used
1db80 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f as a [SQLITE_RO
1db90 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 LLBACK | return
1dba0 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 code].** from th
1dbb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f e [sqlite3_vtab_
1dbc0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 on_conflict()] i
1dbd0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 nterface..*/.#de
1dbe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 fine SQLITE_DENY
1dbf0 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 1 /* Abort
1dc00 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1dc10 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 t with an error
1dc20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1dc30 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 E_IGNORE 2 /*
1dc40 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 Don't allow acce
1dc50 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 ss, but don't ge
1dc60 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 nerate an error
1dc70 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
1dc80 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 EF: Authorizer A
1dc90 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a ction Codes.**.*
1dca0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
1dcb0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d et_authorizer()]
1dcc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
1dcd0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 ters a callback
1dce0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 function.** that
1dcf0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 is invoked to a
1dd00 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e uthorize certain
1dd10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
1dd20 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 ctions. The.**
1dd30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1dd40 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1dd50 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 is an integer c
1dd60 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 ode that specifi
1dd70 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f es.** what actio
1dd80 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f n is being autho
1dd90 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 rized. These ar
1dda0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 e the integer ac
1ddb0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a tion codes that.
1ddc0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ** the authorize
1ddd0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 r callback may b
1dde0 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 e passed..**.**
1ddf0 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 These action cod
1de00 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 e values signify
1de10 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 what kind of op
1de20 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 eration is to be
1de30 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 .** authorized.
1de40 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 The 3rd and 4th
1de50 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 parameters to t
1de60 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e he authorization
1de70 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e .** callback fun
1de80 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 ction will be pa
1de90 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c rameters or NULL
1dea0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 depending on wh
1deb0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ich of these.**
1dec0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 codes is used as
1ded0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1dee0 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 meter. ^(The 5t
1def0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
1df00 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
1df10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
1df20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 name of the dat
1df30 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 abase ("main", "
1df40 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 temp",.** etc.)
1df50 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e if applicable.)^
1df60 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d ^The 6th param
1df70 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 eter to the auth
1df80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a orizer callback.
1df90 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
1dfa0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 f the inner-most
1dfb0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 trigger or view
1dfc0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 that is respons
1dfd0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 ible for.** the
1dfe0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f access attempt o
1dff0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 r NULL if this a
1e000 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 ccess attempt is
1e010 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a directly from.*
1e020 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 * top-level SQL
1e030 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a code..*/./******
1e040 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e050 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e060 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a ***** 3rd ******
1e070 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a ****** 4th *****
1e080 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 ******/.#define
1e090 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e SQLITE_CREATE_IN
1e0a0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 DEX 1
1e0b0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1e0c0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1e0d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1e0e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 QLITE_CREATE_TAB
1e0f0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 LE 2
1e100 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1e110 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1e120 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e130 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
1e140 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f _INDEX 3 /
1e150 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1e160 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1e170 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e180 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1e190 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a TABLE 4 /*
1e1a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1e1b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1e1c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e1d0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
1e1e0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 RIGGER 5 /*
1e1f0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1e200 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1e210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e220 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 E_CREATE_TEMP_VI
1e230 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 EW 6 /* V
1e240 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1e250 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1e260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e270 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 _CREATE_TRIGGER
1e280 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 7 /* Tr
1e290 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
1e2a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1e2b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e2c0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 CREATE_VIEW
1e2d0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 8 /* Vie
1e2e0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
1e2f0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1e300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1e310 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
1e320 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 9 /* Tabl
1e330 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1e340 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1e350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1e360 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 OP_INDEX
1e370 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 10 /* Index
1e380 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1e390 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1e3a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1e3b0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 P_TABLE
1e3c0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 11 /* Table
1e3d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1e3e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1e3f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1e400 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
1e410 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 12 /* Index N
1e420 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
1e430 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1e440 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1e450 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 TEMP_TABLE
1e460 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 13 /* Table Na
1e470 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1e480 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1e490 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1e4a0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 EMP_TRIGGER 1
1e4b0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 4 /* Trigger N
1e4c0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1e4d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1e4e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
1e4f0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 MP_VIEW 15
1e500 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1e510 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1e520 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1e530 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 SQLITE_DROP_TRI
1e540 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 GGER 16
1e550 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
1e560 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
1e570 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e580 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 SQLITE_DROP_VIEW
1e590 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 17
1e5a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
1e5b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1e5c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1e5d0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 QLITE_INSERT
1e5e0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 18
1e5f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1e600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1e610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e620 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 LITE_PRAGMA
1e630 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 19 /
1e640 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 * Pragma Name
1e650 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 1st arg or NUL
1e660 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c L */.#define SQL
1e670 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 ITE_READ
1e680 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 /*
1e690 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1e6a0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 Column Name
1e6b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e6c0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 TE_SELECT
1e6d0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 21 /*
1e6e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1e6f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1e700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e710 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 E_TRANSACTION
1e720 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 22 /* O
1e730 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e peration N
1e740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1e750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e760 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 _UPDATE
1e770 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 23 /* Ta
1e780 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f ble Name Co
1e790 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f lumn Name */
1e7a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e7b0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 ATTACH
1e7c0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 24 /* Fil
1e7d0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c ename NUL
1e7e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1e7f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1e800 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 ETACH
1e810 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 25 /* Data
1e820 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c base Name NULL
1e830 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1e840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c define SQLITE_AL
1e850 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 TER_TABLE
1e860 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 26 /* Datab
1e870 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 ase Name Table
1e880 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1e890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 efine SQLITE_REI
1e8a0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 NDEX
1e8b0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 27 /* Index
1e8c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1e8d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1e8e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c fine SQLITE_ANAL
1e8f0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 YZE
1e900 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 28 /* Table N
1e910 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1e920 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1e930 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1e940 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 E_VTABLE
1e950 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 29 /* Table Na
1e960 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e me Module N
1e970 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
1e980 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 ne SQLITE_DROP_V
1e990 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 TABLE 3
1e9a0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
1e9b0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
1e9c0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
1e9d0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f e SQLITE_FUNCTIO
1e9e0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 N 31
1e9f0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
1ea00 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e Function N
1ea10 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 ame */.#define
1ea20 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e SQLITE_SAVEPOIN
1ea30 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 T 32
1ea40 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
1ea50 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e Savepoint N
1ea60 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ame */.#define
1ea70 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 SQLITE_COPY
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 0
1ea90 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 /* No longer us
1eaa0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ed */../*.** CAP
1eab0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 I3REF: Tracing A
1eac0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e nd Profiling Fun
1ead0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ctions.**.** The
1eae0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 se routines regi
1eaf0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 ster callback fu
1eb00 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e nctions that can
1eb10 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 be used for.**
1eb20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 tracing and prof
1eb30 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 iling the execut
1eb40 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 ion of SQL state
1eb50 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
1eb60 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
1eb70 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 ion registered b
1eb80 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 y sqlite3_trace(
1eb90 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a ) is invoked at.
1eba0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 ** various times
1ebb0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 when an SQL sta
1ebc0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 tement is being
1ebd0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f run by [sqlite3_
1ebe0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 step()]..** ^The
1ebf0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
1ec00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1ec10 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d oked with a UTF-
1ec20 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 8 rendering of t
1ec30 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d he.** SQL statem
1ec40 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 ent text as the
1ec50 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 statement first
1ec60 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 begins executing
1ec70 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 ..** ^(Additiona
1ec80 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 l sqlite3_trace(
1ec90 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 ) callbacks migh
1eca0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 t occur.** as ea
1ecb0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 ch triggered sub
1ecc0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 program is enter
1ecd0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 ed. The callbac
1ece0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a ks for triggers.
1ecf0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 ** contain a UTF
1ed00 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 -8 SQL comment t
1ed10 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 hat identifies t
1ed20 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a he trigger.)^.**
1ed30 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
1ed40 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 TRACE_SIZE_LIMIT
1ed50 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1ed60 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
1ed70 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 d to limit.** th
1ed80 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 e length of [bou
1ed90 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 nd parameter] ex
1eda0 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f pansion in the o
1edb0 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 utput of sqlite3
1edc0 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 _trace()..**.**
1edd0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
1ede0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
1edf0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
1ee00 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
1ee10 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
1ee20 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
1ee30 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 hes. ^The profi
1ee40 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
1ee50 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
1ee60 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
1ee70 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
1ee80 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
1ee90 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
1eea0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
1eeb0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
1eec0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
1eed0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 callback.** time
1eee0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 is in units of
1eef0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 nanoseconds, how
1ef00 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 ever the current
1ef10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
1ef20 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 ** is only capab
1ef30 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e le of millisecon
1ef40 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 d resolution so
1ef50 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 the six least si
1ef60 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 gnificant.** dig
1ef70 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 its in the time
1ef80 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e are meaningless.
1ef90 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
1efa0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d s of SQLite.** m
1efb0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 ight provide gre
1efc0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 ater resolution
1efd0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 on the profiler
1efe0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a callback. The.*
1eff0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c * sqlite3_profil
1f000 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
1f010 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 considered exper
1f020 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a imental and is.*
1f030 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 * subject to cha
1f040 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 nge in future ve
1f050 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1f060 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
1f070 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
1f080 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 *, void(*xTrace)
1f090 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
1f0a0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
1f0b0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
1f0c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
1f0d0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
1f0e0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
1f0f0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
1f100 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
1f110 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
1f120 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f130 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
1f140 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
1f150 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 The sqlite3_prog
1f160 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e ress_handler(D,N
1f170 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 ,X,P) interface
1f180 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 causes the callb
1f190 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
1f1a0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 X to be invoked
1f1b0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
1f1c0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 ing long running
1f1d0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
1f1e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b lite3_exec()], [
1f1f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1f200 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 and [sqlite3_get
1f210 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a _table()] for.**
1f220 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1f230 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d tion D. An exam
1f240 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
1f250 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
1f260 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
1f270 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
1f280 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
1f290 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 ** ^The paramete
1f2a0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 r P is passed th
1f2b0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c rough as the onl
1f2c0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 y parameter to t
1f2d0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 he .** callback
1f2e0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 function X. ^Th
1f2f0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 e parameter N is
1f300 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 the approximate
1f310 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b number of .** [
1f320 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
1f330 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 instructions] th
1f340 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 at are evaluated
1f350 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 between success
1f360 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ive.** invocatio
1f370 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 ns of the callba
1f380 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 ck X. ^If N is
1f390 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 less than one th
1f3a0 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a en the progress.
1f3b0 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 ** handler is di
1f3c0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f sabled..**.** ^O
1f3d0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f nly a single pro
1f3e0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 gress handler ma
1f3f0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 y be defined at
1f400 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 one time per.**
1f410 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1f420 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 tion]; setting a
1f430 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 new progress ha
1f440 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 ndler cancels th
1f450 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e e.** old one. ^
1f460 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 Setting paramete
1f470 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 r X to NULL disa
1f480 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 bles the progres
1f490 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 s handler..** ^T
1f4a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1f4b0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 ler is also disa
1f4c0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 bled by setting
1f4d0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 N to a value les
1f4e0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a s.** than 1..**.
1f4f0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 ** ^If the progr
1f500 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
1f510 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
1f520 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a he operation is.
1f530 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 ** interrupted.
1f540 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 This feature ca
1f550 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 n be used to imp
1f560 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e lement a.** "Can
1f570 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 cel" button on a
1f580 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 GUI progress di
1f590 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 alog box..**.**
1f5a0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
1f5b0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 dler callback mu
1f5c0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
1f5d0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
1f5e0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
1f5f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
1f600 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1f610 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
1f620 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
1f630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1f640 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
1f650 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
1f660 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
1f670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f680 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
1f690 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
1f6a0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
1f6b0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 ph..**.*/.void s
1f6c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
1f6d0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
1f6e0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
1f6f0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
1f700 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
1f710 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
1f720 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
1f730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
1f740 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 utines open an S
1f750 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 QLite database f
1f760 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 ile as specified
1f770 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 by the .** file
1f780 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e name argument. ^
1f790 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
1f7a0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
1f7b0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f eted as UTF-8 fo
1f7c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
1f7d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
1f7e0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 open_v2() and as
1f7f0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
1f800 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 ative byte.** or
1f810 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f der for sqlite3_
1f820 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 open16(). ^(A [d
1f830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f840 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 on] handle is us
1f850 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 ually.** returne
1f860 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e d in *ppDb, even
1f870 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 if an error occ
1f880 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 urs. The only e
1f890 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 xception is that
1f8a0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 .** if SQLite is
1f8b0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
1f8c0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f ate memory to ho
1f8d0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d ld the [sqlite3]
1f8e0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 object,.** a NU
1f8f0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 LL will be writt
1f900 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e en into *ppDb in
1f910 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 stead of a point
1f920 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
1f930 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e e3].** object.)^
1f940 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 ^(If the databa
1f950 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e se is opened (an
1f960 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 d/or created) su
1f970 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
1f980 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 .** [SQLITE_OK]
1f990 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
1f9a0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
1f9b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
1f9c0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b ned.)^ ^The.** [
1f9d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
1f9e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
1f9f0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
1fa00 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
1fa10 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
1fa20 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
1fa30 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
1fa40 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 he error followi
1fa50 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 ng a failure of
1fa60 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 any.** of the sq
1fa70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 lite3_open() rou
1fa80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tines..**.** ^Th
1fa90 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
1faa0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 ng for the datab
1fab0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ase will be UTF-
1fac0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 8 if.** sqlite3_
1fad0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
1fae0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 3_open_v2() is c
1faf0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
1fb00 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
1fb10 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
1fb20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1fb30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
1fb40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
1fb50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
1fb60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
1fb70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
1fb80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1fb90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1fba0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
1fbb0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
1fbc0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
1fbd0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
1fbe0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
1fbf0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
1fc00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
1fc10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
1fc20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
1fc30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
1fc40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
1fc50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
1fc60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
1fc70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
1fc80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
1fc90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
1fca0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
1fcb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 ection. ^(The f
1fcc0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
1fcd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
1fce0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 n_v2() can take
1fcf0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
1fd00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
1fd10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
1fd20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
1fd30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
1fd40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
1fd50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1fd60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
1fd70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
1fd80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ,.** [SQLITE_OPE
1fd90 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c N_PRIVATECACHE],
1fda0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
1fdb0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a OPEN_URI] flags:
1fdc0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a )^.**.** <dl>.**
1fdd0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
1fde0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 PEN_READONLY]</d
1fdf0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
1fe00 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1fe10 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f in read-only mo
1fe20 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 de. If the data
1fe30 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
1fe40 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
1fe50 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
1fe60 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
1fe70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
1fe80 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
1fe90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1fea0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1feb0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
1fec0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 and writing if p
1fed0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 ossible, or read
1fee0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 ing.** only if t
1fef0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 he file is write
1ff00 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 protected by th
1ff10 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
1ff20 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a em. In either.*
1ff30 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 * case the datab
1ff40 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 ase must already
1ff50 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 exist, otherwis
1ff60 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 e an error is re
1ff70 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
1ff80 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
1ff90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
1ffa0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 E] | [SQLITE_OPE
1ffb0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a N_CREATE]</dt>.*
1ffc0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
1ffd0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
1ffe0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
1fff0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 ting, and is cre
20000 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f ated if.** it do
20010 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
20020 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
20030 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
20040 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
20050 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
20060 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
20070 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 _open16().</dd>)
20080 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a ^.** </dl>.**.**
20090 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
200a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
200b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
200c0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
200d0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
200e0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 wn above optiona
200f0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
20100 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 h other.** [SQLI
20110 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
20120 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a | SQLITE_OPEN_*
20130 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 bits].** then t
20140 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
20150 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
20160 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
20170 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
20180 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
20190 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
201a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
201b0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
201c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
201d0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
201e0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
201f0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
20200 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
20210 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
20220 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 tart-time. ^If
20230 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
20240 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
20250 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
20260 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
20270 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
20280 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
20290 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
202a0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
202b0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
202c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
202d0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
202e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
202f0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 e..** ^The [SQLI
20300 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
20310 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
20320 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
20330 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
20340 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
20350 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
20360 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
20370 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
20380 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
20390 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
203a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
203b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
203c0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b e()]. ^The.** [
203d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
203e0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
203f0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
20400 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
20410 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
20420 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
20430 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
20440 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
20450 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
20460 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
20470 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
20480 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
20490 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
204a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
204b0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
204c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
204d0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
204e0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
204f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
20500 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
20510 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
20520 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
20530 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
20540 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
20550 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
20560 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s used..**.** ^I
20570 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
20580 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 s ":memory:", th
20590 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
205a0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 mporary in-memor
205b0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 y database.** is
205c0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
205d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 connection. ^T
205e0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 his in-memory da
205f0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 tabase will vani
20600 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 sh when.** the d
20610 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20620 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
20630 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
20640 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
20650 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 * make use of ad
20660 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c ditional special
20670 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 filenames that
20680 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 begin with the "
20690 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a :" character..**
206a0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
206b0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 ed that when a d
206c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
206d0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 actually does b
206e0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 egin with.** a "
206f0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 :" character you
20700 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 should prefix t
20710 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 he filename with
20720 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 a pathname such
20730 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 as.** "./" to a
20740 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a void ambiguity..
20750 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
20760 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
20770 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
20780 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
20790 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 rary.** on-disk
207a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
207b0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 created. ^This
207c0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 private databas
207d0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 e will be.** aut
207e0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
207f0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
20800 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
20810 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
20820 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c .**.** [[URI fil
20830 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 enames in sqlite
20840 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 3_open()]] <h3>U
20850 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 RI Filenames</h3
20860 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 >.**.** ^If [URI
20870 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 filename] inter
20880 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
20890 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 bled, and the fi
208a0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
208b0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 ** begins with "
208c0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 file:", then the
208d0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 filename is int
208e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 erpreted as a UR
208f0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e I. ^URI.** filen
20900 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
20910 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 on is enabled if
20920 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
20930 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a N_URI] flag is.*
20940 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 * set in the fou
20950 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
20960 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
20970 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a ), or if it has.
20980 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 ** been enabled
20990 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 globally using t
209a0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
209b0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 G_URI] option wi
209c0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 th the.** [sqlit
209d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 e3_config()] met
209e0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 hod or by the [S
209f0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 QLITE_USE_URI] c
20a00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
20a10 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c on..** As of SQL
20a20 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
20a30 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 7, URI filename
20a40 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
20a50 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 s turned off.**
20a60 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 by default, but
20a70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
20a80 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 of SQLite might
20a90 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e enable URI filen
20aa0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ame.** interpret
20ab0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 ation by default
20ac0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c . See "[URI fil
20ad0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 enames]" for add
20ae0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
20af0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 mation..**.** UR
20b00 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 I filenames are
20b10 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 parsed according
20b20 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 to RFC 3986. ^I
20b30 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 f the URI contai
20b40 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 ns an.** authori
20b50 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 ty, then it must
20b60 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d be either an em
20b70 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 pty string or th
20b80 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f e string .** "lo
20b90 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 calhost". ^If th
20ba0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e e authority is n
20bb0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 ot an empty stri
20bc0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 ng or "localhost
20bd0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 ", an .** error
20be0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 is returned to t
20bf0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 he caller. ^The
20c00 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 fragment compone
20c10 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 nt of a URI, if
20c20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 .** present, is
20c30 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
20c40 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
20c50 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f path component o
20c60 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 f the URI as the
20c70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 name of the dis
20c80 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 k file.** which
20c90 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 contains the dat
20ca0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 abase. ^If the p
20cb0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 ath begins with
20cc0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c a '/' character,
20cd0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 .** then it is
20ce0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
20cf0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e n absolute path.
20d00 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f ^If the path do
20d10 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a es not begin .**
20d20 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 with a '/' (mea
20d30 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 ning that the au
20d40 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 thority section
20d50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
20d60 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e the URI).** then
20d70 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 the path is int
20d80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 erpreted as a re
20d90 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a lative path. .**
20da0 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 ^On windows, th
20db0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e e first componen
20dc0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 t of an absolute
20dd0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 path .** is a d
20de0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 rive specificati
20df0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a on (e.g. "C:")..
20e00 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 **.** [[core URI
20e10 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
20e20 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 s]].** The query
20e30 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
20e40 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 URI may contain
20e50 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
20e60 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a are interpreted.
20e70 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c ** either by SQL
20e80 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 ite itself, or b
20e90 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f y a [VFS | custo
20ea0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 m VFS implementa
20eb0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 tion]..** SQLite
20ec0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
20ed0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
20ee0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
20ef0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
20f00 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 <li> <b>vfs</b
20f10 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 >: ^The "vfs" pa
20f20 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 rameter may be u
20f30 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 sed to specify t
20f40 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 he name of.**
20f50 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 a VFS object t
20f60 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 hat provides the
20f70 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
20f80 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
20f90 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 should.** b
20fa0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 e used to access
20fb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
20fc0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 le on disk. ^If
20fd0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 this option is s
20fe0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 et to.** an
20ff0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 empty string the
21000 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a default VFS obj
21010 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 ect is used. ^Sp
21020 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
21030 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 own.** VFS i
21040 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 s an error. ^If
21050 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
21060 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
21070 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a e vfs option is.
21080 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 ** present,
21090 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 then the VFS spe
210a0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 cified by the op
210b0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 tion takes prece
210c0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 dence over.**
210d0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 the value pass
210e0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 ed as the fourth
210f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
21100 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
21110 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
21120 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 >mode</b>: ^(The
21130 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
21140 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 may be set to ei
21150 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c ther "ro", "rw",
21160 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f .** "rwc", o
21170 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 r "memory". Atte
21180 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 mpting to set it
21190 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 to any other va
211a0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e lue is.** an
211b0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 error)^. .**
211c0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 ^If "ro" is sp
211d0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 ecified, then th
211e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
211f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e ened for read-on
21200 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 ly .** acces
21210 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 s, just as if th
21220 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
21230 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 EADONLY] flag ha
21240 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 d been set in th
21250 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 e .** third
21260 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
21270 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e te3_open_v2(). ^
21280 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 If the mode opti
21290 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a on is set to .**
212a0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 "rw", then
212b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
212c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d opened for read-
212d0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 write (but not c
212e0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 reate) .** a
212f0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c ccess, as if SQL
21300 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
21310 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 TE (but not SQLI
21320 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 TE_OPEN_CREATE)
21330 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e had .** been
21340 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 set. ^Value "rw
21350 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 c" is equivalent
21360 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 to setting both
21370 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f .** SQLITE_
21380 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 OPEN_READWRITE a
21390 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 nd SQLITE_OPEN_C
213a0 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 REATE. ^If the
213b0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a mode option is.*
213c0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 * set to "me
213d0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 mory" then a pur
213e0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 e [in-memory dat
213f0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 abase] that neve
21400 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f r reads.** o
21410 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 r writes from di
21420 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 sk is used. ^It
21430 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 is an error to s
21440 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 pecify a value f
21450 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f or.** the mo
21460 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 de parameter tha
21470 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 t is less restri
21480 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 ctive than that
21490 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
214a0 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 the flags pa
214b0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 ssed in the thir
214c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
214d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
214e0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c ..**.** <li> <
214f0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 b>cache</b>: ^Th
21500 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 e cache paramete
21510 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
21520 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 either "shared"
21530 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 or.** "priva
21540 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 te". ^Setting it
21550 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 to "shared" is
21560 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
21570 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 tting the.**
21580 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
21590 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 REDCACHE bit in
215a0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
215b0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 nt passed to.**
215c0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e sqlite3_open
215d0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 _v2(). ^Setting
215e0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 the cache parame
215f0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 ter to "private"
21600 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 is .** equi
21610 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
21620 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 g the SQLITE_OPE
21630 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 N_PRIVATECACHE b
21640 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 it..** ^If s
21650 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
21660 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
21670 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 "cache" paramet
21680 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e er is present in
21690 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 .** a URI fi
216a0 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 lename, its valu
216b0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 e overrides any
216c0 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 behavior request
216d0 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a ed by setting.**
216e0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
216f0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 _PRIVATECACHE or
21700 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
21710 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a REDCACHE flag..*
21720 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 * </ul>.**.** ^S
21730 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
21740 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 nown parameter i
21750 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 n the query comp
21760 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 onent of a URI i
21770 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f s not an.** erro
21780 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 r. Future versi
21790 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
217a0 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 ght understand a
217b0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a dditional query.
217c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ** parameters.
217d0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 See "[query para
217e0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 meters with spec
217f0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 ial meaning to S
21800 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 QLite]" for.** a
21810 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
21820 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 ation..**.** [[U
21830 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
21840 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 ples]] <h3>URI f
21850 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 ilename examples
21860 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 </h3>.**.** <tab
21870 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c le border="1" al
21880 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 ign=center cellp
21890 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 adding=5>.** <tr
218a0 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 ><th> URI filena
218b0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 mes <th> Results
218c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
218d0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a e:data.db <td> .
218e0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
218f0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e the file "data.
21900 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 db" in the curre
21910 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a nt directory..**
21920 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
21930 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
21940 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 b<br>.**
21950 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 file:///home/f
21960 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
21970 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 .** fi
21980 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 le://localhost/h
21990 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
219a0 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 <br> <td> .**
219b0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 Open the
219c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 database file "
219d0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
219e0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e db"..** <tr><td>
219f0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 file://darkstar
21a00 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
21a10 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
21a20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 An error. "
21a30 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 darkstar" is not
21a40 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 a recognized au
21a50 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e thority..** <tr>
21a60 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 <td style="white
21a70 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 -space:nowrap">
21a80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
21a90 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 e:///C:/Document
21aa0 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e s%20and%20Settin
21ab0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f gs/fred/Desktop/
21ac0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c data.db.** <
21ad0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 td> Windows only
21ae0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 : Open the file
21af0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 "data.db" on fre
21b00 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 d's desktop on d
21b10 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 rive.**
21b20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 C:. Note that t
21b30 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 he %20 escaping
21b40 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 in this example
21b50 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 is not strictly
21b60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 .** nec
21b70 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 essary - space c
21b80 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 haracters can be
21b90 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a used literally.
21ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 ** in U
21bb0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a RI filenames..**
21bc0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
21bd0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 ata.db?mode=ro&c
21be0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 ache=private <td
21bf0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
21c00 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 pen file "data.d
21c10 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
21c20 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 t directory for
21c30 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 read-only access
21c40 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 ..** Re
21c50 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
21c60 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
21c70 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 d-cache mode is
21c80 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 enabled by.**
21c90 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 default,
21ca0 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 use a private ca
21cb0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e che..** <tr><td>
21cc0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
21cd0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 /data.db?vfs=uni
21ce0 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a x-nolock <td>.**
21cf0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
21d00 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
21d10 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 data.db". Use th
21d20 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 e special VFS "u
21d30 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 nix-nolock"..**
21d40 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
21d50 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f ta.db?mode=reado
21d60 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 nly <td> .**
21d70 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 An error.
21d80 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f "readonly" is no
21d90 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e t a valid option
21da0 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 for the "mode"
21db0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f parameter..** </
21dc0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 table>.**.** ^UR
21dd0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 I hexadecimal es
21de0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 cape sequences (
21df0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 %HH) are support
21e00 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 ed within the pa
21e10 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 th and.** query
21e20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 components of a
21e30 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d URI. A hexadecim
21e40 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
21e50 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 ce consists of a
21e60 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e .** percent sign
21e70 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 - "%" - followe
21e80 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f d by exactly two
21e90 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 hexadecimal dig
21ea0 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 its .** specifyi
21eb0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 ng an octet valu
21ec0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 e. ^Before the p
21ed0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d ath or query com
21ee0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 ponents of a.**
21ef0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 URI filename are
21f00 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 interpreted, th
21f10 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 ey are encoded u
21f20 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 sing UTF-8 and a
21f30 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d ll .** hexadecim
21f40 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
21f50 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 ces replaced by
21f60 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f a single byte co
21f70 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
21f80 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 corresponding oc
21f90 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f tet. If this pro
21fa0 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 cess generates a
21fb0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 n invalid UTF-8
21fc0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 encoding,.** the
21fd0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
21fe0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 efined..**.** <b
21ff0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
22000 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
22010 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
22020 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
22030 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
22040 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
22050 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
22060 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
22070 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
22080 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
22090 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
220a0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
220b0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
220c0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
220d0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
220e0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
220f0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
22100 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
22110 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
22120 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
22130 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
22140 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
22150 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
22160 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
22170 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
22180 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
22190 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f alling sqlite3_o
221a0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
221b0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 _open_v2(). Oth
221c0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
221d0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
221e0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
221f0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
22200 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a les may fail..**
22210 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
22220 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
22230 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 ctory].*/.int sq
22240 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
22250 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
22260 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
22270 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
22280 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
22290 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
222a0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
222b0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
222c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
222d0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
222e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
222f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
22300 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
22310 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
22320 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
22330 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
22340 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
22350 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
22360 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
22370 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
22380 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
22390 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
223a0 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
223b0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
223c0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
223d0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
223e0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
223f0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
22400 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
22410 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
22420 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
22430 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22440 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f Obtain Values Fo
22450 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 r URI Parameters
22460 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
22470 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 utility routine
22480 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 s, useful to VFS
22490 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
224a0 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 , that check.**
224b0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 to see if a data
224c0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 base file was a
224d0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e URI that contain
224e0 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 ed a specific qu
224f0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ery .** paramete
22500 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 r, and if so obt
22510 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f ains the value o
22520 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 f that query par
22530 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 ameter..**.** If
22540 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 F is the databa
22550 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e se filename poin
22560 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ter passed into
22570 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 the xOpen() meth
22580 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 od of .** a VFS
22590 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
225a0 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 hen the flags pa
225b0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
225c0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a () has one or .*
225d0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 * more of the [S
225e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
225f0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or [SQLITE_OPEN_
22600 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 MAIN_DB] bits se
22610 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 t and.** P is th
22620 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 e name of the qu
22630 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 ery parameter, t
22640 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 hen.** sqlite3_u
22650 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 ri_parameter(F,P
22660 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 ) returns the va
22670 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 lue of the P.**
22680 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 parameter if it
22690 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c exists or a NULL
226a0 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f pointer if P do
226b0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 es not appear as
226c0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 a .** query par
226d0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 ameter on F. If
226e0 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 P is a query pa
226f0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 rameter of F.**
22700 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 has no explicit
22710 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 value, then sqli
22720 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
22730 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a r(F,P) returns.*
22740 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
22750 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a n empty string..
22760 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
22770 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
22780 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 P,B) routine ass
22790 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 umes that P is a
227a0 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 boolean.** para
227b0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e meter and return
227c0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 s true (1) or fa
227d0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e lse (0) accordin
227e0 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a g to the value.*
227f0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c * of P. The sql
22800 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
22810 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
22820 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 returns true (1)
22830 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 if the.** value
22840 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 of query parame
22850 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 ter P is one of
22860 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f "yes", "true", o
22870 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a r "on" in any.**
22880 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 case or if the
22890 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 value begins wit
228a0 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d h a non-zero num
228b0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 ber. The .** sq
228c0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
228d0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
228e0 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 s returns false
228f0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 (0) if the value
22900 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 of.** query par
22910 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
22920 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 of "no", "false"
22930 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e , or "off" in an
22940 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 y case or.** if
22950 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
22960 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 with a numeric
22970 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e zero. If P is n
22980 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 ot a query.** pa
22990 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 rameter on F or
229a0 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 if the value of
229b0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 P is does not ma
229c0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a tch any of the.*
229d0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 * above, then sq
229e0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
229f0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 n(F,P,B) returns
22a00 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 (B!=0)..**.** T
22a10 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 he sqlite3_uri_i
22a20 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 nt64(F,P,D) rout
22a30 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ine converts the
22a40 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f value of P into
22a50 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 a.** 64-bit sig
22a60 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 ned integer and
22a70 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 returns that int
22a80 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 eger, or D if P
22a90 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 does not.** exis
22aa0 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 t. If the value
22ab0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 of P is somethi
22ac0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e ng other than an
22ad0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a integer, then.*
22ae0 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e * zero is return
22af0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 ed..** .** If F
22b00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
22b10 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f r, then sqlite3_
22b20 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
22b30 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 P) returns NULL
22b40 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 and.** sqlite3_u
22b50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
22b60 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 ) returns B. If
22b70 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c F is not a NULL
22b80 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 pointer and.**
22b90 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
22ba0 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 e file pathname
22bb0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c pointer that SQL
22bc0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ite passed into
22bd0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 the xOpen.** VFS
22be0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 method, then th
22bf0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
22c00 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e is routine is un
22c10 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
22c20 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 ably.** undesira
22c30 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ble..*/.const ch
22c40 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f ar *sqlite3_uri_
22c50 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 parameter(const
22c60 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c char *zFilename,
22c70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
22c80 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ram);.int sqlite
22c90 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 3_uri_boolean(co
22ca0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c nst char *zFile,
22cb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
22cc0 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c ram, int bDefaul
22cd0 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 t);.sqlite3_int6
22ce0 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 4 sqlite3_uri_in
22cf0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c t64(const char*,
22d00 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 const char*, sq
22d10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a lite3_int64);...
22d20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22d30 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
22d40 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e Messages.**.** ^
22d50 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 The sqlite3_errc
22d60 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ode() interface
22d70 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
22d80 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 ric [result code
22d90 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
22da0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 d result code] f
22db0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 or the most rece
22dc0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 nt failed sqlite
22dd0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 3_* API call.**
22de0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
22df0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
22e00 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 ection]. If a pr
22e10 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 ior API call fai
22e20 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d led.** but the m
22e30 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 ost recent API c
22e40 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 all succeeded, t
22e50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
22e60 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f from.** sqlite3_
22e70 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 errcode() is und
22e80 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 efined. ^The sq
22e90 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
22ea0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
22eb0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
22ec0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
22ed0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
22ee0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
22ef0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
22f00 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
22f10 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
22f20 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
22f30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
22f40 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
22f50 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
22f60 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
22f70 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
22f80 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
22f90 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
22fa0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
22fb0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
22fc0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 ely..** ^(Memory
22fd0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
22fe0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
22ff0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
23000 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
23010 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
23020 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
23030 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 ry about freeing
23040 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
23050 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 However, the err
23060 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 or string might
23070 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f be overwritten o
23080 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 r deallocated by
23090 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 .** subsequent c
230a0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 alls to other SQ
230b0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 Lite interface f
230c0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a unctions.)^.**.*
230d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
230e0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 rrstr() interfac
230f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e e returns the En
23100 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
23110 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 ext.** that desc
23120 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c ribes the [resul
23130 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d t code], as UTF-
23140 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 8..** ^(Memory t
23150 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
23160 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
23170 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
23180 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 nally.** and mus
23190 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 t not be freed b
231a0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
231b0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 n)^..**.** When
231c0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
231d0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
231e0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
231f0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
23200 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
23210 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
23220 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
23230 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
23240 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
23250 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
23260 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
23270 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
23280 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
23290 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
232a0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
232b0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
232c0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
232d0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
232e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
232f0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
23300 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
23310 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
23320 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
23330 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
23340 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
23350 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
23360 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
23370 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
23380 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
23390 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
233a0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
233b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
233c0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
233d0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
233e0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
233f0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
23400 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
23410 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
23420 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
23430 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
23440 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
23450 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
23460 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
23470 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
23480 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
23490 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
234a0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
234b0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
234c0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
234d0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
234e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
234f0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
23500 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
23510 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
23520 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
23530 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
23540 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
23550 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
23560 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
23570 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
23580 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
23590 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a rrstr(int);../*.
235a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
235b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
235c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
235d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
235e0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 nt} {prepared st
235f0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 atements}.**.**
23600 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
23610 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
23620 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 sents a single S
23630 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a QL statement..**
23640 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 This object is
23650 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 variously known
23660 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 as a "prepared s
23670 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a tatement" or a.*
23680 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 * "compiled SQL
23690 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 statement" or si
236a0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 mply as a "state
236b0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment"..**.** The
236c0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 life of a state
236d0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 ment object goes
236e0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 something like
236f0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e this:.**.** <ol>
23700 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 .** <li> Create
23710 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
23720 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
23730 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c e_v2()] or a rel
23740 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e ated.** fun
23750 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 ction..** <li> B
23760 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 ind values to [h
23770 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 ost parameters]
23780 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
23790 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 3_bind_*().**
237a0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a interfaces..*
237b0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 * <li> Run the S
237c0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 QL by calling [s
237d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
237e0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
237f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 ..** <li> Reset
23800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 the statement us
23810 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
23820 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 et()] then go ba
23830 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 ck.** to st
23840 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a ep 2. Do this z
23850 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 ero or more time
23860 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 s..** <li> Destr
23870 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 oy the object us
23880 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
23890 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f alize()]..** </o
238a0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 l>.**.** Refer t
238b0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 o documentation
238c0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 on individual me
238d0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 thods above for
238e0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
238f0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 formation..*/.ty
23900 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
23910 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
23920 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
23930 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
23940 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e e Limits.**.** ^
23950 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 (This interface
23960 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 allows the size
23970 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 of various const
23980 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 ructs to be limi
23990 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e ted.** on a conn
239a0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 ection by connec
239b0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 tion basis. The
239c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
239d0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 is the.** [data
239e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
239f0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 whose limit is
23a00 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 to be set or que
23a10 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ried. The.** se
23a20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
23a30 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 s one of the [li
23a40 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 mit categories]
23a50 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a that define a.**
23a60 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 class of constr
23a70 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 ucts to be size
23a80 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 limited. The th
23a90 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
23aa0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 the.** new limi
23ab0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 t for that const
23ac0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 ruct.)^.**.** ^I
23ad0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 f the new limit
23ae0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 is a negative nu
23af0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 mber, the limit
23b00 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a is unchanged..**
23b10 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 ^(For each limi
23b20 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 t category SQLIT
23b30 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c E_LIMIT_<i>NAME<
23b40 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a /i> there is a .
23b50 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 ** [limits | har
23b60 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a d upper bound].*
23b70 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 * set at compile
23b80 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 -time by a C pre
23b90 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
23ba0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 called.** [limit
23bb0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c s | SQLITE_MAX_<
23bc0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 i>NAME</i>]..**
23bd0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 (The "_LIMIT_" i
23be0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 n the name is ch
23bf0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 anged to "_MAX_"
23c00 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 .))^.** ^Attempt
23c10 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
23c20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
23c30 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
23c40 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
23c50 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
23c60 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 e hard upper bou
23c70 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 nd..**.** ^Regar
23c80 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
23c90 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 or not the limi
23ca0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 t was changed, t
23cb0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f he .** [sqlite3_
23cc0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 limit()] interfa
23cd0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 ce returns the p
23ce0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 rior value of th
23cf0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e e limit..** ^Hen
23d00 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 ce, to find the
23d10 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
23d20 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 a limit without
23d30 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a changing it,.**
23d40 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 simply invoke t
23d50 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 his interface wi
23d60 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 th the third par
23d70 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 ameter set to -1
23d80 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 ..**.** Run-time
23d90 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 limits are inte
23da0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
23db0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
23dc0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 t manage.** both
23dd0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 their own inter
23de0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 nal database and
23df0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 also databases
23e00 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c that are control
23e10 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 led.** by untrus
23e20 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 ted external sou
23e30 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c rces. An exampl
23e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
23e50 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 ght be a.** web
23e60 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
23e70 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
23e80 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
23e90 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
23ea0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
23eb0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
23ec0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
23ed0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
23ee0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
23ef0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
23f00 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
23f10 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
23f20 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
23f30 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
23f40 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
23f50 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
23f60 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
23f70 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
23f80 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
23f90 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
23fa0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
23fb0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
23fc0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
23fd0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
23fe0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
23ff0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
24000 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
24010 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
24020 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
24030 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
24040 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
24050 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
24060 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
24070 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
24080 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
24090 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
240a0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
240b0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
240c0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
240d0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
240e0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
240f0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
24100 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
24110 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
24120 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
24130 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
24140 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
24150 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
24160 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {*limit categori
24170 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
24180 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
24190 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
241a0 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
241b0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
241c0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
241d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
241e0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
241f0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
24200 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
24210 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
24220 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
24230 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
24240 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
24250 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
24260 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
24270 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
24280 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
24290 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 T_LENGTH]] ^(<dt
242a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 >SQLITE_LIMIT_LE
242b0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
242c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a >The maximum siz
242d0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 e of any string
242e0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 or BLOB or table
242f0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c row, in bytes.<
24300 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
24310 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
24320 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
24330 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
24340 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
24350 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
24360 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 ngth of an SQL s
24370 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 tatement, in byt
24380 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a es.</dd>)^.**.**
24390 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
243a0 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 COLUMN]] ^(<dt>S
243b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
243c0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 MN</dt>.** <dd>T
243d0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
243e0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
243f0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 a table definiti
24400 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 on or in the.**
24410 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
24420 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 [SELECT] or the
24430 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
24440 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 f columns in an
24450 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 index.** or in a
24460 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 n ORDER BY or GR
24470 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f OUP BY clause.</
24480 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
24490 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
244a0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
244b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
244c0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
244d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
244e0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
244f0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
24500 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a ression.</dd>)^.
24510 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
24520 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
24530 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LECT]] ^(<dt>SQL
24540 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
24550 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
24560 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
24570 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
24580 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
24590 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
245a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
245b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 [SQLITE_LIMIT_VD
245c0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 BE_OP]] ^(<dt>SQ
245d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
245e0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OP</dt>.** <dd>T
245f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
24600 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e r of instruction
24610 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d s in a virtual m
24620 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a achine program.*
24630 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d * used to implem
24640 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 ent an SQL state
24650 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 ment. This limi
24660 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 t is not current
24670 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 ly.** enforced,
24680 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 though that migh
24690 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f t be added in so
246a0 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
246b0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c e of.** SQLite.<
246c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
246d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
246e0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 TION_ARG]] ^(<dt
246f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
24700 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
24710 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
24720 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
24730 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
24740 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tion.</dd>)^.**.
24750 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
24760 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c T_ATTACHED]] ^(<
24770 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
24780 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a ATTACHED</dt>.**
24790 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
247a0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 number of [ATTA
247b0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 CH | attached da
247c0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e tabases].)^</dd>
247d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
247e0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
247f0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e RN_LENGTH]].** ^
24800 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
24810 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
24820 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
24830 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
24840 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
24850 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
24860 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a the [LIKE] or.**
24870 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
24880 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
24890 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [[SQLITE_LIMIT_V
248a0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d ARIABLE_NUMBER]]
248b0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
248c0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
248d0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c NUMBER</dt>.** <
248e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 dd>The maximum i
248f0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 ndex number of a
24900 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 ny [parameter] i
24910 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
24920 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 nt.)^.**.** [[SQ
24930 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
24940 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 ER_DEPTH]] ^(<dt
24950 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 >SQLITE_LIMIT_TR
24960 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e IGGER_DEPTH</dt>
24970 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
24980 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
24990 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
249a0 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c ers.</dd>)^.** <
249b0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
249c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
249d0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
249e0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
249f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 SQLITE_LIMIT_SQ
24a00 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 L_LENGTH
24a10 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
24a20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
24a30 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 OLUMN
24a40 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
24a50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
24a60 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 EXPR_DEPTH
24a70 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 3.#def
24a80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
24a90 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
24aa0 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
24ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
24ac0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 T_VDBE_OP
24ad0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
24ae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
24af0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 IT_FUNCTION_ARG
24b00 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 6.#
24b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
24b20 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 MIT_ATTACHED
24b30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 7.
24b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
24b50 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
24b60 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 N_LENGTH 8
24b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24b80 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
24b90 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 UMBER
24ba0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
24bb0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
24bc0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
24bd0 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
24be0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
24bf0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
24c00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
24c10 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
24c20 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 ler}.**.** To ex
24c30 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 ecute an SQL que
24c40 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 ry, it must firs
24c50 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e t be compiled in
24c60 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a to a byte-code.*
24c70 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 * program using
24c80 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 one of these rou
24c90 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tines..**.** The
24ca0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c first argument,
24cb0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 "db", is a [dat
24cc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24cd0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 ] obtained from
24ce0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 a.** prior succe
24cf0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
24d00 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
24d10 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
24d20 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
24d30 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 e3_open16()]. T
24d40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
24d50 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 ection must not
24d60 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 have been closed
24d70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
24d80 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 nd argument, "zS
24d90 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 ql", is the stat
24da0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
24db0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a iled, encoded.**
24dc0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
24dd0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 or UTF-16. The
24de0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
24df0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
24e00 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 repare_v2().** i
24e10 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 nterfaces use UT
24e20 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 F-8, and sqlite3
24e30 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 _prepare16() and
24e40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
24e50 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 16_v2().** use U
24e60 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 TF-16..**.** ^If
24e70 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
24e80 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e ent is less than
24e90 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c zero, then zSql
24ea0 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 is read up to t
24eb0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f he.** first zero
24ec0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 terminator. ^If
24ed0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 nByte is non-ne
24ee0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 gative, then it
24ef0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a is the maximum.*
24f00 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 * number of byt
24f10 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 es read from zSq
24f20 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 l. ^When nByte
24f30 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
24f40 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 the.** zSql str
24f50 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 ing ends at eith
24f60 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 er the first '\0
24f70 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 00' or '\u0000'
24f80 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 character or.**
24f90 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 the nByte-th byt
24fa0 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d e, whichever com
24fb0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 es first. If the
24fc0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a caller knows.**
24fd0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 that the suppli
24fe0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c ed string is nul
24ff0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 -terminated, the
25000 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 n there is a sma
25010 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 ll.** performanc
25020 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 e advantage to b
25030 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 e gained by pass
25040 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 ing an nByte par
25050 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 ameter that.** i
25060 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e s equal to the n
25070 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
25080 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 n the input stri
25090 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c ng <i>including<
250a0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 /i>.** the nul-t
250b0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 erminator bytes
250c0 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 as this saves SQ
250d0 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 Lite from having
250e0 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f to.** make a co
250f0 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 py of the input
25100 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 string..**.** ^I
25110 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 f pzTail is not
25120 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 NULL then *pzTai
25130 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 l is made to poi
25140 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 nt to the first
25150 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 byte.** past the
25160 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 end of the firs
25170 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
25180 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 in zSql. These
25190 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a routines only.**
251a0 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 compile the fir
251b0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 st statement in
251c0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c zSql, so *pzTail
251d0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
251e0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d g to.** what rem
251f0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e ains uncompiled.
25200 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 .**.** ^*ppStmt
25210 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
25220 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b to a compiled [
25230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25240 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a nt] that can be.
25250 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e ** executed usin
25260 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
25270 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 )]. ^If there i
25280 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 s an error, *ppS
25290 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f tmt is set.** to
252a0 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 NULL. ^If the
252b0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
252c0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
252d0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
252e0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
252f0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
25300 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
25310 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 to NULL..** The
25320 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 calling procedu
25330 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c re is responsibl
25340 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 e for deleting t
25350 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 he compiled.** S
25360 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 QL statement usi
25370 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
25380 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
25390 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
253a0 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 th it..** ppStmt
253b0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c may not be NULL
253c0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 ..**.** ^On succ
253d0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ess, the sqlite3
253e0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c _prepare() famil
253f0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 y of routines re
25400 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
25410 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 ;.** otherwise a
25420 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
25430 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
25440 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 * The sqlite3_pr
25450 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 epare_v2() and s
25460 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
25470 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 _v2() interfaces
25480 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e are.** recommen
25490 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 ded for all new
254a0 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 programs. The tw
254b0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 o older interfac
254c0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a es are retained.
254d0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ** for backwards
254e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 compatibility,
254f0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 but their use is
25500 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a discouraged..**
25510 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e ^In the "v2" in
25520 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 terfaces, the pr
25530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25540 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 .** that is retu
25550 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 rned (the [sqlit
25560 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 e3_stmt] object)
25570 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 contains a copy
25580 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 of the.** origi
25590 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 nal SQL text. Th
255a0 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 is causes the [s
255b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 qlite3_step()] i
255c0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 nterface to.** b
255d0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c ehave differentl
255e0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a y in three ways:
255f0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
25600 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 li>.** ^If the d
25610 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
25620 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 hanges, instead
25630 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 of returning [SQ
25640 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 LITE_SCHEMA] as
25650 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 it.** always use
25660 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 d to do, [sqlite
25670 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 3_step()] will a
25680 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 utomatically rec
25690 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a ompile the SQL.*
256a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 * statement and
256b0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 try to run it ag
256c0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 ain. As many as
256d0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 [SQLITE_MAX_SCHE
256e0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 MA_RETRY].** ret
256f0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 ries will occur
25700 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 before sqlite3_s
25710 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 tep() gives up a
25720 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 nd returns an er
25730 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ror..** </li>.**
25740 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 .** <li>.** ^Whe
25750 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 n an error occur
25760 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 s, [sqlite3_step
25770 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
25780 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 one of the detai
25790 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f led.** [error co
257a0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 des] or [extende
257b0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 d error codes].
257c0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 ^The legacy beh
257d0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a avior was that.*
257e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
257f0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 )] would only re
25800 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b turn a generic [
25810 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 SQLITE_ERROR] re
25820 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 sult code.** and
25830 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
25840 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d would have to m
25850 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c ake a second cal
25860 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 l to [sqlite3_re
25870 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 set()].** in ord
25880 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 er to find the u
25890 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 nderlying cause
258a0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 of the problem.
258b0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 With the "v2" pr
258c0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 epare.** interfa
258d0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 ces, the underly
258e0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 ing reason for t
258f0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 he error is retu
25900 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
25910 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a ..** </li>.**.**
25920 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 <li>.** ^If the
25930 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 specific value
25940 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 bound to [parame
25950 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d ter | host param
25960 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a eter] in the .**
25970 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 WHERE clause mi
25980 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 ght influence th
25990 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 e choice of quer
259a0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 y plan for a sta
259b0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 tement,.** then
259c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 the statement wi
259d0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
259e0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 lly recompiled,
259f0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 as if there had
25a00 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d been .** a schem
25a10 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 a change, on the
25a20 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 first [sqlite3
25a30 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f _step()] call fo
25a40 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e llowing any chan
25a50 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 ge.** to the [sq
25a60 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 lite3_bind_text
25a70 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 | bindings] of t
25a80 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e hat [parameter].
25a90 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 .** ^The specif
25aa0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 ic value of WHER
25ab0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 E-clause [parame
25ac0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 ter] might influ
25ad0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f ence the .** cho
25ae0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 ice of query pla
25af0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 n if the paramet
25b00 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 er is the left-h
25b10 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c and side of a [L
25b20 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 IKE].** or [GLOB
25b30 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 ] operator or if
25b40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
25b50 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e s compared to an
25b60 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a indexed column.
25b70 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 ** and the [SQLI
25b80 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d TE_ENABLE_STAT3]
25b90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
25ba0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e tion is enabled.
25bb0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 .** the .** </li
25bc0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e >.** </ol>.*/.in
25bd0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
25be0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
25bf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
25c00 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
25c10 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
25c20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
25c30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
25c40 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
25c50 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
25c60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
25c70 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
25c80 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
25c90 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
25ca0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
25cb0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
25cc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
25cd0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
25ce0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
25cf0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
25d00 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
25d10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
25d20 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 pare_v2(. sqlit
25d30 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
25d40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
25d50 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
25d60 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
25d70 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
25d80 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
25d90 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
25da0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
25db0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
25dc0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
25dd0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
25de0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
25df0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
25e00 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
25e10 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
25e20 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
25e30 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
25e40 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
25e50 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
25e60 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
25e70 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
25e80 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
25e90 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
25ea0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
25eb0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
25ec0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
25ed0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
25ee0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
25ef0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
25f00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
25f10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
25f20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
25f30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
25f40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
25f50 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
25f60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
25f70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
25f80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
25f90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
25fa0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
25fb0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 16_v2(. sqlite3
25fc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
25fd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
25fe0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
25ff0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
26000 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
26010 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
26020 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
26030 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
26040 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
26050 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
26060 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
26070 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
26080 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
26090 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
260a0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
260b0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
260c0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
260d0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
260e0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
260f0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e I3REF: Retrievin
26100 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a g Statement SQL.
26110 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
26120 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
26130 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
26140 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
26150 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
26160 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
26170 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
26180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
26190 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
261a0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
261b0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
261c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
261d0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
261e0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
261f0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
26200 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 qlite3_sql(sqlit
26210 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
26220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26230 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
26240 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
26250 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 Writes The Datab
26260 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ase.**.** ^The s
26270 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
26280 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 only(X) interfac
26290 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
262a0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 non-zero) if.**
262b0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 and only if the
262c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
262d0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 ent] X makes no
262e0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 direct changes t
262f0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 o.** the content
26300 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
26310 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 file..**.** Not
26320 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 e that [applicat
26330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
26340 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a functions] or.**
26350 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 [virtual tables
26360 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 ] might change t
26370 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 he database indi
26380 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 rectly as a side
26390 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 effect. .** ^(
263a0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 For example, if
263b0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 an application d
263c0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f efines a functio
263d0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 n "eval()" that
263e0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 .** calls [sqlit
263f0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e e3_exec()], then
26400 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
26410 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 QL statement wou
26420 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 ld.** change the
26430 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
26440 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 hrough side-effe
26450 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 cts:.**.** <bloc
26460 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
26470 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 SELECT eval('
26480 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 DELETE FROM t1')
26490 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 FROM t2;.** </p
264a0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
264b0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 .**.** But becau
264c0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 se the [SELECT]
264d0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
264e0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ot change the da
264f0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 tabase file.** d
26500 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 irectly, sqlite3
26510 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
26520 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 would still ret
26530 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a urn true.)^.**.*
26540 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 * ^Transaction c
26550 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 ontrol statement
26560 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e s such as [BEGIN
26570 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f ], [COMMIT], [RO
26580 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 LLBACK],.** [SAV
26590 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 EPOINT], and [RE
265a0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c LEASE] cause sql
265b0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
265c0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
265d0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 rue,.** since th
265e0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 e statements the
265f0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 mselves do not a
26600 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 ctually modify t
26610 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a he database but.
26620 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 ** rather they c
26630 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e ontrol the timin
26640 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 g of when other
26650 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 statements modif
26660 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 y the .** databa
26670 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 se. ^The [ATTAC
26680 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 H] and [DETACH]
26690 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 statements also
266a0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 cause.** sqlite3
266b0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
266c0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 to return true
266d0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f since, while tho
266e0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a se statements.**
266f0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 change the conf
26700 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 iguration of a d
26710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26720 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 on, they do not
26730 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 make .** changes
26740 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 to the content
26750 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
26760 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a files on disk..*
26770 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 /.int sqlite3_st
26780 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 mt_readonly(sqli
26790 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
267a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
267b0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
267c0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
267d0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 ment Has Been Re
267e0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 set.**.** ^The s
267f0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
26800 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (S) interface re
26810 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
26820 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 zero) if the.**
26830 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26840 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 ent] S has been
26850 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 stepped at least
26860 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 once using .**
26870 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
26880 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 ] but has not ru
26890 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 n to completion
268a0 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a and/or has not .
268b0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 ** been reset us
268c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
268d0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 et(S)]. ^The sq
268e0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
268f0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 S).** interface
26900 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 returns false if
26910 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 S is a NULL poi
26920 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e nter. If S is n
26930 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f ot a .** NULL po
26940 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 inter and is not
26950 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
26960 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 valid [prepared
26970 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
26980 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 ject, then the b
26990 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
269a0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c ined and probabl
269b0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a y undesirable..*
269c0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
269d0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
269e0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b in combination [
269f0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
26a00 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 t()].** to locat
26a10 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 e all prepared s
26a20 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 tatements associ
26a30 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 ated with a data
26a40 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 base .** connect
26a50 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 ion that are in
26a60 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 need of being re
26a70 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 set. This can b
26a80 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 e used,.** for e
26a90 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e xample, in diagn
26aa0 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 ostic routines t
26ab0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 o search for pre
26ac0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d pared .** statem
26ad0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f ents that are ho
26ae0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 lding a transact
26af0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 ion open..*/.int
26b00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
26b10 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a sy(sqlite3_stmt*
26b20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26b30 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 EF: Dynamically
26b40 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 Typed Value Obje
26b50 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
26b60 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 {protected sqlit
26b70 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f e3_value} {unpro
26b80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
26b90 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 alue}.**.** SQLi
26ba0 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 te uses the sqli
26bb0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
26bc0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c to represent al
26bd0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 l values.** that
26be0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 can be stored i
26bf0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
26c00 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 le. SQLite uses
26c10 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a dynamic typing.*
26c20 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 * for the values
26c30 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 it stores. ^Va
26c40 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 lues stored in s
26c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
26c60 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 ects.** can be i
26c70 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
26c80 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
26c90 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
26ca0 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 or NULL..**.** A
26cb0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
26cc0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 object may be ei
26cd0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 ther "protected"
26ce0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 or "unprotected
26cf0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 "..** Some inter
26d00 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 faces require a
26d10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
26d20 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 3_value. Other
26d30 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 interfaces.** wi
26d40 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 ll accept either
26d50 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 a protected or
26d60 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
26d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
26d80 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 Every interface
26d90 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 that accepts sq
26da0 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 lite3_value argu
26db0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a ments specifies.
26dc0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ** whether or no
26dd0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 t it requires a
26de0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
26df0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 3_value..**.** T
26e00 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 he terms "protec
26e10 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 ted" and "unprot
26e20 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 ected" refer to
26e30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a whether or not.*
26e40 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c * a mutex is hel
26e50 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 d. An internal
26e60 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f mutex is held fo
26e70 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a r a protected.**
26e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
26e90 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 bject but no mut
26ea0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 ex is held for a
26eb0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a n unprotected.**
26ec0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
26ed0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 bject. If SQLit
26ee0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f e is compiled to
26ef0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 be single-threa
26f00 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 ded.** (with [SQ
26f10 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
26f20 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 0] and with [sql
26f30 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
26f40 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a )] returning 0).
26f50 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 ** or if SQLite
26f60 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 is run in one of
26f70 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d reduced mutex m
26f80 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 odes .** [SQLITE
26f90 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
26fa0 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 READ] or [SQLITE
26fb0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
26fc0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 EAD].** then the
26fd0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 re is no distinc
26fe0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f tion between pro
26ff0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
27000 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
27010 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
27020 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 and they can be
27030 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 used interchange
27040 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a ably. However,.
27050 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 ** for maximum c
27060 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 ode portability
27070 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
27080 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
27090 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b ons.** still mak
270a0 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f e the distinctio
270b0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
270c0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
270d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
270e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 alue objects eve
270f0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 n when not stric
27100 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a tly required..**
27110 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27120 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 _value objects t
27130 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 hat are passed a
27140 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 s parameters int
27150 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 o the.** impleme
27160 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c ntation of [appl
27170 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27180 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 SQL functions] a
27190 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a re protected..**
271a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
271b0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 lue object retur
271c0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
271d0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
271e0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 )] is unprotecte
271f0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 d..** Unprotecte
27200 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
27210 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 objects may only
27220 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a be used with.**
27230 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
27240 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
27250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
27260 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 e()]..** The [sq
27270 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 lite3_value_blob
27280 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 | sqlite3_value
27290 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 _type()] family
272a0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 of.** interfaces
272b0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 require protect
272c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
272d0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 objects..*/.typ
272e0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 edef struct Mem
272f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a sqlite3_value;..
27300 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27310 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e SQL Function Con
27320 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a text Object.**.*
27330 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e * The context in
27340 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 which an SQL fu
27350 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 nction executes
27360 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a is stored in an.
27370 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ** sqlite3_conte
27380 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 xt object. ^A p
27390 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c ointer to an sql
273a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
273b0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ect.** is always
273c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
273d0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e to [application
273e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
273f0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 ctions]..** The
27400 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
27410 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
27420 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
27430 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a will pass this.*
27440 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 * pointer throug
27450 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 h into calls to
27460 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
27470 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 int | sqlite3_re
27480 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c sult()],.** [sql
27490 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
274a0 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 ontext()], [sqli
274b0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
274c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f ,.** [sqlite3_co
274d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
274e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 )], [sqlite3_get
274f0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 _auxdata()],.**
27500 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f and/or [sqlite3_
27510 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a set_auxdata()]..
27520 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
27530 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
27540 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
27550 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
27560 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 EF: Binding Valu
27570 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 es To Prepared S
27580 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 tatements.** KEY
27590 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 WORDS: {host par
275a0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 ameter} {host pa
275b0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 rameters} {host
275c0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a parameter name}.
275d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
275e0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 L parameter} {SQ
275f0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 L parameters} {p
27600 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
27610 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 }.**.** ^(In the
27620 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
27630 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ext input to [sq
27640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
27650 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
27660 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c ants,.** literal
27670 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
27680 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 d by a [paramete
27690 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 r] that matches
276a0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 one of following
276b0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a .** templates:.*
276c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
276d0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
276e0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
276f0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
27700 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
27710 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
27720 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f he templates abo
27730 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e ve, NNN represen
27740 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 ts an integer li
27750 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
27760 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 V represents an
27770 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 alphanumeric ide
27780 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 ntifier.)^ ^The
27790 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
277a0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 .** parameters (
277b0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
277c0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
277d0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d s" or "SQL param
277e0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
277f0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
27800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
27810 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
27820 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d here..**.** ^T
27830 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
27840 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
27850 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
27860 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 es is always.**
27870 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
27880 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
27890 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
278a0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 from.** [sqlite3
278b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
278c0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a r its variants..
278d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
278e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
278f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 e index of the S
27900 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 QL parameter to
27910 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 be set..** ^The
27920 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
27930 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
27940 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e dex of 1. ^When
27950 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a the same named.
27960 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
27970 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 is used more th
27980 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 an once, second
27990 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a and subsequent.*
279a0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 * occurrences ha
279b0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 ve the same inde
279c0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f x as the first o
279d0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 ccurrence..** ^T
279e0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d he index for nam
279f0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 ed parameters ca
27a00 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 n be looked up u
27a10 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
27a20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
27a30 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 ter_index()] API
27a40 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 if desired. ^T
27a50 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 he index.** for
27a60 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 "?NNN" parameter
27a70 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f s is the value o
27a80 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e f NNN..** ^The N
27a90 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 NN value must be
27aa0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 between 1 and t
27ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 he [sqlite3_limi
27ac0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 t()].** paramete
27ad0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f r [SQLITE_LIMIT_
27ae0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
27af0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a (default value:
27b00 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 999)..**.** ^Th
27b10 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
27b20 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
27b30 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
27b40 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 ameter..** ^If t
27b50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
27b60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
27b70 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c nd_text() or sql
27b80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
27b90 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
27ba0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 _bind_blob() is
27bb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
27bc0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 hen the fourth p
27bd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 arameter.** is i
27be0 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 gnored and the e
27bf0 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 nd result is the
27c00 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 same as sqlite3
27c10 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a _bind_null()..**
27c20 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 .** ^(In those r
27c30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 outines that hav
27c40 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d e a fourth argum
27c50 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 ent, its value i
27c60 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
27c70 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
27c80 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 parameter. To b
27c90 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c e clear: the val
27ca0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
27cb0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c ber of <u>bytes<
27cc0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 /u> in the value
27cd0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
27ce0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 of characters.)
27cf0 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 ^.** ^If the fou
27d00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
27d10 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
27d20 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f xt() or sqlite3_
27d30 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a bind_text16().**
27d40 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
27d50 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 en the length of
27d60 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a the string is.*
27d70 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
27d80 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 bytes up to the
27d90 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
27da0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 nator..** If the
27db0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
27dc0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
27dd0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 d_blob() is nega
27de0 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 tive, then.** th
27df0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
27e00 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 defined..** If a
27e10 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f non-negative fo
27e20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
27e30 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 s provided to sq
27e40 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
27e50 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
27e60 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 bind_text16() th
27e70 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 en that paramete
27e80 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 r must be the by
27e90 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 te offset.** whe
27ea0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 re the NUL termi
27eb0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 nator would occu
27ec0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 r assuming the s
27ed0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a tring were NUL.*
27ee0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 * terminated. I
27ef0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 f any NUL charac
27f00 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 ters occur at by
27f10 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 te offsets less
27f20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c than .** the val
27f30 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 ue of the fourth
27f40 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 parameter then
27f50 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
27f60 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a ring value will.
27f70 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 ** contain embed
27f80 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 ded NULs. The r
27f90 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 esult of express
27fa0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 ions involving s
27fb0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 trings.** with e
27fc0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 mbedded NULs is
27fd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
27fe0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 ^The fifth argu
27ff0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
28000 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c bind_blob(), sql
28010 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
28020 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 , and.** sqlite3
28030 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 _bind_text16() i
28040 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 s a destructor u
28050 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f sed to dispose o
28060 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a f the BLOB or.**
28070 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 string after SQ
28080 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 Lite has finishe
28090 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 d with it. ^The
280a0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 destructor is c
280b0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 alled.** to disp
280c0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
280d0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 or string even i
280e0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 f the call to sq
280f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
28100 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 ),.** sqlite3_bi
28110 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 nd_text(), or sq
28120 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
28130 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 6() fails. .**
28140 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 ^If the fifth ar
28150 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 gument is.** the
28160 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b special value [
28170 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 SQLITE_STATIC],
28180 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 then SQLite assu
28190 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
281a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 information is i
281b0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 n static, unmana
281c0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f ged space and do
281d0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
281e0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 e freed..** ^If
281f0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
28200 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 nt has the value
28210 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
28220 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c NT], then.** SQL
28230 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 ite makes its ow
28240 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
28250 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 f the data immed
28260 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a iately, before.*
28270 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 * the sqlite3_bi
28280 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 nd_*() routine r
28290 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eturns..**.** ^T
282a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
282b0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 zeroblob() routi
282c0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 ne binds a BLOB
282d0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 of length N that
282e0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 .** is filled wi
282f0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a th zeroes. ^A z
28300 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 eroblob uses a f
28310 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d ixed amount of m
28320 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 emory.** (just a
28330 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c n integer to hol
28340 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c d its size) whil
28350 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 e it is being pr
28360 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f ocessed..** Zero
28370 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 blobs are intend
28380 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 ed to serve as p
28390 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
283a0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 BLOBs whose.** c
283b0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 ontent is later
283c0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a written using.**
283d0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
283e0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 pen | incrementa
283f0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 l BLOB I/O] rout
28400 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 ines..** ^A nega
28410 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 tive value for t
28420 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 he zeroblob resu
28430 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 lts in a zero-le
28440 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a ngth BLOB..**.**
28450 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 ^If any of the
28460 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
28470 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
28480 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
28490 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 pointer.** for
284a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
284b0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 atement] or with
284c0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
284d0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a ement for which.
284e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
284f0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c ()] has been cal
28500 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c led more recentl
28510 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f y than [sqlite3_
28520 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 reset()],.** the
28530 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 n the call will
28540 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d return [SQLITE_M
28550 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 ISUSE]. If any
28560 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a sqlite3_bind_().
28570 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 ** routine is pa
28580 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 ssed a [prepared
28590 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
285a0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
285b0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 zed, the.** resu
285c0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 lt is undefined
285d0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 and probably har
285e0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e mful..**.** ^Bin
285f0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c dings are not cl
28600 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 eared by the [sq
28610 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 lite3_reset()] r
28620 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f outine..** ^Unbo
28630 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 und parameters a
28640 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 re interpreted a
28650 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s NULL..**.** ^T
28660 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
28670 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 * routines retur
28680 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
28690 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a success or an.*
286a0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 * [error code] i
286b0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 f anything goes
286c0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 wrong..** ^[SQLI
286d0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 TE_RANGE] is ret
286e0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 urned if the par
286f0 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 ameter.** index
28700 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e is out of range.
28710 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ^[SQLITE_NOMEM
28720 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 ] is returned if
28730 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e malloc() fails.
28740 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
28750 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
28760 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
28770 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
28780 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
28790 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 me()], and [sqli
287a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
287b0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a er_index()]..*/.
287c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
287d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
287e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
287f0 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f void*, int n, vo
28800 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
28810 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
28820 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
28830 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
28840 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
28850 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 bind_int(sqlite3
28860 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
28870 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
28880 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
28890 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
288a0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e lite3_int64);.in
288b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
288c0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
288d0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c *, int);.int sql
288e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
288f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
28900 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 t, const char*,
28910 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
28920 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
28930 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
28940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
28950 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
28960 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
28970 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 id*));.int sqlit
28980 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 e3_bind_value(sq
28990 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
289a0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f , const sqlite3_
289b0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
289c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
289d0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
289e0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a , int, int n);..
289f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28a00 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 Number Of SQL Pa
28a10 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e rameters.**.** ^
28a20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e This routine can
28a30 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 be used to find
28a40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b the number of [
28a50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a SQL parameters].
28a60 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 ** in a [prepare
28a70 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 d statement]. S
28a80 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 QL parameters ar
28a90 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a e tokens of the.
28aa0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e ** form "?", "?N
28ab0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 NN", ":AAA", "$A
28ac0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 AA", or "@AAA" t
28ad0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 hat serve as.**
28ae0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 placeholders for
28af0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 values that are
28b00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
28b10 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 lob | bound].**
28b20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
28b30 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d s at a later tim
28b40 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 e..**.** ^(This
28b50 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 routine actually
28b60 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 returns the ind
28b70 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ex of the larges
28b80 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a t (rightmost).**
28b90 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 parameter. For
28ba0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 all forms except
28bb0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c ?NNN, this will
28bc0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 correspond to t
28bd0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
28be0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 unique parameter
28bf0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 s. If parameter
28c00 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f s of the ?NNN fo
28c10 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 rm are used,.**
28c20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 there may be gap
28c30 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e s in the list.)^
28c40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
28c50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
28c60 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
28c70 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
28c80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
28c90 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 name()], and.**
28ca0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
28cb0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
28cc0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
28cd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
28ce0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
28cf0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
28d00 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
28d10 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a Host Parameter.
28d20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
28d30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
28d40 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 r_name(P,N) inte
28d50 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a rface returns.**
28d60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
28d70 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d N-th [SQL param
28d80 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 eter] in the [pr
28d90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28da0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 ] P..** ^(SQL pa
28db0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
28dc0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 form "?NNN" or "
28dd0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
28de0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 or "$AAA".** hav
28df0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 e a name which i
28e00 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e s the string "?N
28e10 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
28e20 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
28e30 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ".** respectivel
28e40 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 y..** In other w
28e50 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 ords, the initia
28e60 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 l ":" or "$" or
28e70 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 "@" or "?".** is
28e80 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 included as par
28e90 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e t of the name.)^
28ea0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 .** ^Parameters
28eb0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 of the form "?"
28ec0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 without a follow
28ed0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 ing integer have
28ee0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 no name.** and
28ef0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 are referred to
28f00 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 as "nameless" or
28f10 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 "anonymous para
28f20 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e meters"..**.** ^
28f30 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 The first host p
28f40 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
28f50 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 index of 1, not
28f60 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 0..**.** ^If the
28f70 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 value N is out
28f80 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 of range or if t
28f90 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 he N-th paramete
28fa0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 r is.** nameless
28fb0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 , then NULL is r
28fc0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 eturned. ^The r
28fd0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
28fe0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 s.** always in U
28ff0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 TF-8 encoding ev
29000 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 en if the named
29010 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a parameter was.**
29020 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 originally spec
29030 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 ified as UTF-16
29040 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 in [sqlite3_prep
29050 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b are16()] or.** [
29060 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
29070 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
29080 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
29090 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
290a0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
290b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
290c0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
290d0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
290e0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
290f0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f _index()]..*/.co
29100 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
29110 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
29120 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
29130 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mt*, int);../*.*
29140 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 * CAPI3REF: Inde
29150 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 x Of A Parameter
29160 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 With A Given Na
29170 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e me.**.** ^Return
29180 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e the index of an
29190 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 SQL parameter g
291a0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 iven its name.
291b0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 ^The.** index va
291c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 lue returned is
291d0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 suitable for use
291e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
291f0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b * parameter to [
29200 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
29210 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
29220 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 ]. ^A zero.** i
29230 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f s returned if no
29240 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 matching parame
29250 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e ter is found. ^
29260 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a The parameter.**
29270 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 name must be gi
29280 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 ven in UTF-8 eve
29290 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 n if the origina
292a0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 l statement.** w
292b0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d as prepared from
292c0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 UTF-16 text usi
292d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
292e0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
292f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
29300 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
29310 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
29320 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
29330 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
29340 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
29350 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
29360 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
29370 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 /.int sqlite3_bi
29380 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
29390 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ex(sqlite3_stmt*
293a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
293b0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ame);../*.** CAP
293c0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c I3REF: Reset All
293d0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 Bindings On A P
293e0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
293f0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 t.**.** ^Contrar
29400 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 y to the intuiti
29410 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c on of many, [sql
29420 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f ite3_reset()] do
29430 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 es not reset.**
29440 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
29450 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 d_blob | binding
29460 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 s] on a [prepare
29470 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
29480 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 ^Use this routi
29490 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 ne to reset all
294a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
294b0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 to NULL..*/.int
294c0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
294d0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
294e0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
294f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f PI3REF: Number O
29500 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 f Columns In A R
29510 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 esult Set.**.**
29520 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 ^Return the numb
29530 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
29540 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
29550 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a returned by the.
29560 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
29570 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 tement]. ^This r
29580 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 outine returns 0
29590 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 if pStmt is an
295a0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 SQL.** statement
295b0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 that does not r
295c0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 eturn data (for
295d0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 example an [UPDA
295e0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 TE])..**.** See
295f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 also: [sqlite3_d
29600 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a ata_count()].*/.
29610 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
29620 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 mn_count(sqlite3
29630 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
29640 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
29650 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 Column Names In
29660 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a A Result Set.**.
29670 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
29680 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 es return the na
29690 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 me assigned to a
296a0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 particular colu
296b0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 mn.** in the res
296c0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
296d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
296e0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ^The sqlite3_c
296f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 olumn_name().**
29700 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
29710 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
29720 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
29730 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
29740 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
29750 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 umn_name16() ret
29760 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
29770 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
29780 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
29790 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 ring. ^The firs
297a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 t parameter is t
297b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
297c0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 tement].** that
297d0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b implements the [
297e0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e SELECT] statemen
297f0 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 t. ^The second p
29800 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a arameter is the.
29810 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 ** column number
29820 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 . ^The leftmost
29830 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 column is numbe
29840 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 r 0..**.** ^The
29850 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
29860 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 pointer is valid
29870 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 until either th
29880 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
29890 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 ement].** is des
298a0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 troyed by [sqlit
298b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f e3_finalize()] o
298c0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 r until the stat
298d0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 ement is automat
298e0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 ically.** reprep
298f0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 ared by the firs
29900 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
29910 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 e3_step()] for a
29920 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a particular run.
29930 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 ** or until the
29940 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 next call to.**
29950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e sqlite3_column_n
29960 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ame() or sqlite3
29970 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 _column_name16()
29980 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c on the same col
29990 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 umn..**.** ^If s
299a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
299b0 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 fails during the
299c0 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 processing of e
299d0 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a ither routine.**
299e0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 (for example du
299f0 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f ring a conversio
29a00 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 n from UTF-8 to
29a10 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a UTF-16) then a.*
29a20 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
29a30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
29a40 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 * ^The name of a
29a50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 result column i
29a60 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
29a70 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 he "AS" clause f
29a80 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d or.** that colum
29a90 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 n, if there is a
29aa0 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 n AS clause. If
29ab0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 there is no AS
29ac0 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 clause.** then t
29ad0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 he name of the c
29ae0 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 olumn is unspeci
29af0 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 fied and may cha
29b00 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 nge from.** one
29b10 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
29b20 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a e to the next..*
29b30 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
29b40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
29b50 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
29b60 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 int N);.const v
29b70 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
29b80 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 umn_name16(sqlit
29b90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 e3_stmt*, int N)
29ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29bb0 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 F: Source Of Dat
29bc0 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 a In A Query Res
29bd0 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ult.**.** ^These
29be0 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 routines provid
29bf0 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 e a means to det
29c00 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 ermine the datab
29c10 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a ase, table, and.
29c20 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 ** table column
29c30 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 that is the orig
29c40 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c in of a particul
29c50 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e ar result column
29c60 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 in.** [SELECT]
29c70 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 statement..** ^T
29c80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
29c90 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 atabase or table
29ca0 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 or column can b
29cb0 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a e returned as.**
29cc0 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 either a UTF-8
29cd0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 or UTF-16 string
29ce0 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 . ^The _databas
29cf0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 e_ routines retu
29d00 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 rn.** the databa
29d10 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 se name, the _ta
29d20 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ble_ routines re
29d30 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e turn the table n
29d40 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 ame, and.** the
29d50 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 origin_ routines
29d60 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 return the colu
29d70 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 mn name..** ^The
29d80 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
29d90 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 is valid until
29da0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
29db0 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 atement] is dest
29dc0 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b royed.** using [
29dd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
29de0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
29df0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 statement is au
29e00 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 tomatically.** r
29e10 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 eprepared by the
29e20 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b first call to [
29e30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
29e40 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
29e50 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c run.** or until
29e60 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d the same inform
29e70 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 ation is request
29e80 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 ed.** again in a
29e90 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 different encod
29ea0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ing..**.** ^The
29eb0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 names returned a
29ec0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 re the original
29ed0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 un-aliased names
29ee0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 of the.** datab
29ef0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 ase, table, and
29f00 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 column..**.** ^T
29f10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
29f20 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 t to these inter
29f30 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 faces is a [prep
29f40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
29f50 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 .** ^These funct
29f60 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f ions return info
29f70 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 rmation about th
29f80 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c e Nth result col
29f90 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a umn returned by.
29fa0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 ** the statement
29fb0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
29fc0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e second function
29fd0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 argument..** ^T
29fe0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c he left-most col
29ff0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 umn is column 0
2a000 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e for these routin
2a010 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 es..**.** ^If th
2a020 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 e Nth column ret
2a030 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 urned by the sta
2a040 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 tement is an exp
2a050 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 ression or.** su
2a060 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f bquery and is no
2a070 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 t a column value
2a080 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 , then all of th
2a090 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
2a0a0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e turn.** NULL. ^
2a0b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 These routine mi
2a0c0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 ght also return
2a0d0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 NULL if a memory
2a0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
2a0f0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f r.** occurs. ^O
2a100 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 therwise, they r
2a110 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f eturn the name o
2a120 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 f the attached d
2a130 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a atabase, table,.
2a140 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 ** or column tha
2a150 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 t query result c
2a160 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 olumn was extrac
2a170 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 ted from..**.**
2a180 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 ^As with all oth
2a190 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 er SQLite APIs,
2a1a0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 those whose name
2a1b0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 s end with "16"
2a1c0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 return.** UTF-16
2a1d0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 encoded strings
2a1e0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 and the other f
2a1f0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 unctions return
2a200 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 UTF-8..**.** ^Th
2a210 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c ese APIs are onl
2a220 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 y available if t
2a230 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 he library was c
2a240 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
2a250 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
2a260 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 LE_COLUMN_METADA
2a270 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 TA] C-preprocess
2a280 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a or symbol..**.**
2a290 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
2a2a0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
2a2b0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 or more of thes
2a2c0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e e routines again
2a2d0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 st the same.** p
2a2e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a2f0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 t and column at
2a300 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
2a310 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2a320 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e re.** undefined.
2a330 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 .**.** If two or
2a340 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 more threads ca
2a350 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a ll one or more.*
2a360 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2a370 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 n_database_name
2a380 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 | column metadat
2a390 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a a interfaces].**
2a3a0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 for the same [p
2a3b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a3c0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f t] and result co
2a3d0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 lumn.** at the s
2a3e0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 ame time then th
2a3f0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
2a400 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 defined..*/.cons
2a410 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2a420 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
2a430 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2a440 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
2a450 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
2a460 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
2a470 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2a480 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 *,int);.const ch
2a490 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2a4a0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 mn_table_name(sq
2a4b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2a4c0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
2a4d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
2a4e0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 le_name16(sqlite
2a4f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2a500 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2a510 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
2a520 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2a530 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 t*,int);.const v
2a540 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
2a550 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 umn_origin_name1
2a560 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2a570 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
2a580 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 I3REF: Declared
2a590 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 Datatype Of A Qu
2a5a0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a ery Result.**.**
2a5b0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 ^(The first par
2a5c0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 ameter is a [pre
2a5d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2a5e0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 ..** If this sta
2a5f0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c tement is a [SEL
2a600 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 ECT] statement a
2a610 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d nd the Nth colum
2a620 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 n of the.** retu
2a630 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 rned result set
2a640 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d of that [SELECT]
2a650 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 is a table colu
2a660 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 mn (not an.** ex
2a670 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2a680 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 uery) then the d
2a690 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 eclared type of
2a6a0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c the table.** col
2a6b0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e umn is returned.
2a6c0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 )^ ^If the Nth
2a6d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
2a6e0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a sult set is an.*
2a6f0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
2a700 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 subquery, then a
2a710 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
2a720 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 returned..** ^T
2a730 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
2a740 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 ng is always UTF
2a750 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a -8 encoded..**.*
2a760 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c * ^(For example,
2a770 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 given the datab
2a780 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a ase schema:.**.*
2a790 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 * CREATE TABLE t
2a7a0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 1(c1 VARIANT);.*
2a7b0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c *.** and the fol
2a7c0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 lowing statement
2a7d0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a to be compiled:
2a7e0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 .**.** SELECT c1
2a7f0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 + 1, c1 FROM t1
2a800 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ;.**.** this rou
2a810 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 tine would retur
2a820 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 n the string "VA
2a830 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 RIANT" for the s
2a840 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 econd result.**
2a850 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 column (i==1), a
2a860 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nd a NULL pointe
2a870 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 r for the first
2a880 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 result column (i
2a890 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 ==0).)^.**.** ^S
2a8a0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d QLite uses dynam
2a8b0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 ic run-time typi
2a8c0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 ng. ^So just be
2a8d0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a cause a column.*
2a8e0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f * is declared to
2a8f0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 contain a parti
2a900 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 cular type does
2a910 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 not mean that th
2a920 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 e.** data stored
2a930 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 in that column
2a940 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 is of the declar
2a950 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 ed type. SQLite
2a960 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 is.** strongly
2a970 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 typed, but the t
2a980 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 yping is dynamic
2a990 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 not static. ^T
2a9a0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 ype.** is associ
2a9b0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 ated with indivi
2a9c0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 dual values, not
2a9d0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 with the contai
2a9e0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 ners.** used to
2a9f0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 hold those value
2aa00 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 s..*/.const char
2aa10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2aa20 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 _decltype(sqlite
2aa30 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2aa40 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2aa50 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
2aa60 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2aa70 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *,int);../*.** C
2aa80 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 API3REF: Evaluat
2aa90 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 e An SQL Stateme
2aaa0 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 nt.**.** After a
2aab0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2aac0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 ment] has been p
2aad0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 repared using ei
2aae0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
2aaf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2ab00 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2ab10 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e re16_v2()] or on
2ab20 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a e of the legacy.
2ab30 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
2ab40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2ab50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ] or [sqlite3_pr
2ab60 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 epare16()], this
2ab70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 function.** mus
2ab80 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 t be called one
2ab90 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f or more times to
2aba0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 evaluate the st
2abb0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 atement..**.** T
2abc0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 he details of th
2abd0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
2abe0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
2abf0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e interface depen
2ac00 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 d.** on whether
2ac10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 the statement wa
2ac20 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 s prepared using
2ac30 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 the newer "v2"
2ac40 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 interface.** [sq
2ac50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2ac60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
2ac70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2ac80 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 or the older le
2ac90 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
2aca0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 e [sqlite3_prepa
2acb0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
2acc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e e3_prepare16()].
2acd0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
2ace0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 .** new "v2" int
2acf0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d erface is recomm
2ad00 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 ended for new ap
2ad10 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 plications but t
2ad20 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
2ad30 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 erface will cont
2ad40 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f inue to be suppo
2ad50 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 rted..**.** ^In
2ad60 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
2ad70 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e face, the return
2ad80 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 value will be e
2ad90 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 ither [SQLITE_BU
2ada0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f SY],.** [SQLITE_
2adb0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 DONE], [SQLITE_R
2adc0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 OW], [SQLITE_ERR
2add0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OR], or [SQLITE_
2ade0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 MISUSE]..** ^Wit
2adf0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
2ae00 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 face, any of the
2ae10 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 other [result c
2ae20 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 odes] or.** [ext
2ae30 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
2ae40 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 es] might be ret
2ae50 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a urned as well..*
2ae60 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 *.** ^[SQLITE_BU
2ae70 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 SY] means that t
2ae80 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 he database engi
2ae90 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f ne was unable to
2aea0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 acquire the.**
2aeb0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 database locks i
2aec0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 t needs to do it
2aed0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 s job. ^If the
2aee0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b statement is a [
2aef0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 COMMIT].** or oc
2af00 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 curs outside of
2af10 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
2af20 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f saction, then yo
2af30 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a u can retry the.
2af40 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 ** statement. I
2af50 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
2af60 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 is not a [COMMIT
2af70 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 ] and occurs wit
2af80 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 hin an.** explic
2af90 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 it transaction t
2afa0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 hen you should r
2afb0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e ollback the tran
2afc0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a saction before.*
2afd0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a * continuing..**
2afe0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e .** ^[SQLITE_DON
2aff0 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 E] means that th
2b000 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 e statement has
2b010 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 finished executi
2b020 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c ng.** successful
2b030 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ly. sqlite3_ste
2b040 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
2b050 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
2b060 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a n this virtual.*
2b070 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 * machine withou
2b080 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 t first calling
2b090 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2b0a0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 ] to reset the v
2b0b0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e irtual.** machin
2b0c0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e e back to its in
2b0d0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a itial state..**.
2b0e0 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 ** ^If the SQL s
2b0f0 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 tatement being e
2b100 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 xecuted returns
2b110 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b any data, then [
2b120 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 SQLITE_ROW].** i
2b130 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 s returned each
2b140 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f time a new row o
2b150 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 f data is ready
2b160 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 for processing b
2b170 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e y the.** caller.
2b180 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 The values may
2b190 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e be accessed usin
2b1a0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 g the [column ac
2b1b0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e cess functions].
2b1c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
2b1d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 () is called aga
2b1e0 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 in to retrieve t
2b1f0 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 he next row of d
2b200 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c ata..**.** ^[SQL
2b210 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 ITE_ERROR] means
2b220 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 that a run-time
2b230 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 error (such as
2b240 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 a constraint.**
2b250 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f violation) has o
2b260 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 ccurred. sqlite
2b270 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
2b280 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
2b290 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d ain on.** the VM
2b2a0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 . More informati
2b2b0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 on may be found
2b2c0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 by calling [sqli
2b2d0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a te3_errmsg()]..*
2b2e0 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 * ^With the lega
2b2f0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 cy interface, a
2b300 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 more specific er
2b310 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 ror code (for ex
2b320 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 ample,.** [SQLIT
2b330 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 E_INTERRUPT], [S
2b340 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b QLITE_SCHEMA], [
2b350 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c SQLITE_CORRUPT],
2b360 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a and so forth).*
2b370 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 * can be obtaine
2b380 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 d by calling [sq
2b390 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2b3a0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 n the.** [prepar
2b3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
2b3c0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 ^In the "v2" int
2b3d0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d erface,.** the m
2b3e0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 ore specific err
2b3f0 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 or code is retur
2b400 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 ned directly by
2b410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a sqlite3_step()..
2b420 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 **.** [SQLITE_MI
2b430 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 SUSE] means that
2b440 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e the this routin
2b450 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 e was called ina
2b460 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a ppropriately..**
2b470 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 Perhaps it was
2b480 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 called on a [pre
2b490 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b4a0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 that has.** alr
2b4b0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 eady been [sqlit
2b4c0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
2b4d0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f nalized] or on o
2b4e0 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 ne that had.** p
2b4f0 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
2b500 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ed [SQLITE_ERROR
2b510 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e ] or [SQLITE_DON
2b520 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 E]. Or it could
2b530 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 .** be the case
2b540 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 that the same da
2b550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2b560 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 n is being used
2b570 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 by two or.** mor
2b580 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 e threads at the
2b590 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 same moment in
2b5a0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 time..**.** For
2b5b0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 all versions of
2b5c0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 SQLite up to and
2b5d0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 including 3.6.2
2b5e0 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 3.1, a call to.*
2b5f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
2b600 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 ()] was required
2b610 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 after sqlite3_s
2b620 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 tep() returned a
2b630 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 nything.** other
2b640 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2b650 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 W] before any su
2b660 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 bsequent invocat
2b670 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 ion of.** sqlite
2b680 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 3_step(). Failu
2b690 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 re to reset the
2b6a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2b6b0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 nt using .** [sq
2b6c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 lite3_reset()] w
2b6d0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
2b6e0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 n [SQLITE_MISUSE
2b6f0 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a ] return from.**
2b700 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
2b710 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 But after vers
2b720 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 ion 3.6.23.1, sq
2b730 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 lite3_step() beg
2b740 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 an.** calling [s
2b750 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2b760 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e automatically in
2b770 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e this circumstan
2b780 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 ce rather.** tha
2b790 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c n returning [SQL
2b7a0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 ITE_MISUSE]. Th
2b7b0 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 is is not consid
2b7c0 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 ered a compatibi
2b7d0 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 lity.** break be
2b7e0 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 cause any applic
2b7f0 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 ation that ever
2b800 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 receives an SQLI
2b810 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a TE_MISUSE error.
2b820 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 ** is broken by
2b830 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 definition. The
2b840 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
2b850 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 TORESET] compile
2b860 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 -time option.**
2b870 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 can be used to r
2b880 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 estore the legac
2b890 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a y behavior..**.*
2b8a0 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 * <b>Goofy Inter
2b8b0 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 face Alert:</b>
2b8c0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e In the legacy in
2b8d0 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c terface, the sql
2b8e0 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 ite3_step().** A
2b8f0 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e PI always return
2b900 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f s a generic erro
2b910 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f r code, [SQLITE_
2b920 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e ERROR], followin
2b930 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f g any.** error o
2b940 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
2b950 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c E_BUSY] and [SQL
2b960 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f ITE_MISUSE]. Yo
2b970 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b u must call.** [
2b980 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2b990 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
2b9a0 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 alize()] in orde
2b9b0 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 r to find one of
2b9c0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
2b9d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 [error codes] t
2b9e0 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 hat better descr
2b9f0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a ibes the error..
2ba00 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 ** We admit that
2ba10 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 this is a goofy
2ba20 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 design. The pr
2ba30 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 oblem has been f
2ba40 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 ixed.** with the
2ba50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e "v2" interface.
2ba60 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 If you prepare
2ba70 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c all of your SQL
2ba80 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 statements.** u
2ba90 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
2baa0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2bab0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
2bac0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 repare16_v2()] i
2bad0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 nstead.** of the
2bae0 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 legacy [sqlite3
2baf0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 _prepare()] and
2bb00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2bb10 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 16()] interfaces
2bb20 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f ,.** then the mo
2bb30 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 re specific [err
2bb40 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 or codes] are re
2bb50 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a turned directly.
2bb60 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 ** by sqlite3_st
2bb70 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f ep(). The use o
2bb80 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 f the "v2" inter
2bb90 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e face is recommen
2bba0 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ded..*/.int sqli
2bbb0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 te3_step(sqlite3
2bbc0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
2bbd0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
2bbe0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
2bbf0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a result set.**.*
2bc00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
2bc10 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 ata_count(P) int
2bc20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
2bc30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
2bc40 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 umns in the.** c
2bc50 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
2bc60 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
2bc70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2bc80 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 ent] P..** ^If p
2bc90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2bca0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 t P does not hav
2bcb0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 e results ready
2bcc0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 to return.** (vi
2bcd0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b a calls to the [
2bce0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
2bcf0 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c nt | sqlite3_col
2bd00 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 umn_*()] of.** i
2bd10 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 nterfaces) then
2bd20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2bd30 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e nt(P) returns 0.
2bd40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2bd50 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
2bd60 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 outine also retu
2bd70 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 rns 0 if P is a
2bd80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
2bd90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
2bda0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 ta_count(P) rout
2bdb0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 ine returns 0 if
2bdc0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
2bdd0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2bde0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 3_step](P) retur
2bdf0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 ned [SQLITE_DONE
2be00 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
2be10 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a _data_count(P).*
2be20 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f * will return no
2be30 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f n-zero if previo
2be40 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 us call to [sqli
2be50 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 te3_step](P) ret
2be60 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 urned.** [SQLITE
2be70 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e _ROW], except in
2be80 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 the case of the
2be90 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 [PRAGMA increme
2bea0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 ntal_vacuum].**
2beb0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 where it always
2bec0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e returns zero sin
2bed0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 ce each step of
2bee0 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a that multi-step.
2bef0 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e ** pragma return
2bf00 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 s 0 columns of d
2bf10 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ata..**.** See a
2bf20 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f lso: [sqlite3_co
2bf30 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f lumn_count()].*/
2bf40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 .int sqlite3_dat
2bf50 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f a_count(sqlite3_
2bf60 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
2bf70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
2bf80 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 undamental Datat
2bf90 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ypes.** KEYWORDS
2bfa0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a : SQLITE_TEXT.**
2bfb0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 .** ^(Every valu
2bfc0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 e in SQLite has
2bfd0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 one of five fund
2bfe0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 amental datatype
2bff0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
2c000 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 <li> 64-bit sig
2c010 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c ned integer.** <
2c020 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 li> 64-bit IEEE
2c030 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e floating point n
2c040 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 umber.** <li> st
2c050 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f ring.** <li> BLO
2c060 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a B.** <li> NULL.*
2c070 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
2c080 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
2c090 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 are codes for ea
2c0a0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 ch of those type
2c0b0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 s..**.** Note th
2c0c0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 at the SQLITE_TE
2c0d0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 XT constant was
2c0e0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c also used in SQL
2c0f0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a ite version 2.**
2c100 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c for a completel
2c110 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e y different mean
2c120 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 ing. Software t
2c130 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 hat links agains
2c140 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 t both.** SQLite
2c150 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 version 2 and S
2c160 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 QLite version 3
2c170 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 should use SQLIT
2c180 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 E3_TEXT, not.**
2c190 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a SQLITE_TEXT..*/.
2c1a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
2c1b0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e NTEGER 1.#defin
2c1c0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 e SQLITE_FLOAT
2c1d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
2c1e0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 TE_BLOB 4.#d
2c1f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c efine SQLITE_NUL
2c200 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 L 5.#ifdef S
2c210 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 QLITE_TEXT.# und
2c220 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 ef SQLITE_TEXT.#
2c230 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 else.# define SQ
2c240 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a LITE_TEXT 3.
2c250 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 #endif.#define S
2c260 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 QLITE3_TEXT
2c270 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 3../*.** CAPI3RE
2c280 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 F: Result Values
2c290 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a From A Query.**
2c2a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 KEYWORDS: {colu
2c2b0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
2c2c0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ons}.**.** These
2c2d0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 routines form t
2c2e0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 he "result set"
2c2f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
2c300 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2c310 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2c320 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 ion about a sing
2c330 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 le column of the
2c340 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 current.** resu
2c350 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 lt row of a quer
2c360 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 y. ^In every ca
2c370 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 se the first arg
2c380 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
2c390 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 er.** to the [pr
2c3a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c3b0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 ] that is being
2c3c0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b evaluated (the [
2c3d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a sqlite3_stmt*].*
2c3e0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 * that was retur
2c3f0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2c400 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2c410 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 or one of its va
2c420 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 riants).** and t
2c430 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2c440 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
2c450 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f of the column fo
2c460 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 r which informat
2c470 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
2c480 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 returned. ^The
2c490 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 leftmost column
2c4a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2c4b0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 t has the index
2c4c0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 0..** ^The numbe
2c4d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
2c4e0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 the result can b
2c4f0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 e determined usi
2c500 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ng.** [sqlite3_c
2c510 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a olumn_count()]..
2c520 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c **.** If the SQL
2c530 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 statement does
2c540 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f not currently po
2c550 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 int to a valid r
2c560 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a ow, or if the.**
2c570 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 column index is
2c580 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 out of range, t
2c590 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 he result is und
2c5a0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 efined..** These
2c5b0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e routines may on
2c5c0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 ly be called whe
2c5d0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
2c5e0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 t call to.** [sq
2c5f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2c600 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 s returned [SQLI
2c610 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 TE_ROW] and neit
2c620 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f her.** [sqlite3_
2c630 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 reset()] nor [sq
2c640 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2c650 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c ] have been call
2c660 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e ed subsequently.
2c670 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 .** If any of th
2c680 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
2c690 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 called after [s
2c6a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2c6b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
2c6c0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 inalize()] or af
2c6d0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ter [sqlite3_ste
2c6e0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
2c6f0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f d.** something o
2c700 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
2c710 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 E_ROW], the resu
2c720 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
2c730 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 d..** If [sqlite
2c740 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
2c750 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2c760 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2c770 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 ize()].** are ca
2c780 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 lled from a diff
2c790 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 erent thread whi
2c7a0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 le any of these
2c7b0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 routines.** are
2c7c0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 pending, then th
2c7d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
2c7e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
2c7f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
2c800 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e mn_type() routin
2c810 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
2c820 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
2c830 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 | datatype code
2c840 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 ] for the initia
2c850 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f l data type.** o
2c860 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c f the result col
2c870 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 umn. ^The retur
2c880 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 ned value is one
2c890 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 of [SQLITE_INTE
2c8a0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 GER],.** [SQLITE
2c8b0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 _FLOAT], [SQLITE
2c8c0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f _TEXT], [SQLITE_
2c8d0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 BLOB], or [SQLIT
2c8e0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 E_NULL]. The va
2c8f0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
2c900 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2c910 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 n_type() is only
2c920 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e meaningful if n
2c930 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 o type.** conver
2c940 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 sions have occur
2c950 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 red as described
2c960 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 below. After a
2c970 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2c980 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 ,.** the value r
2c990 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2c9a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2c9b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
2c9c0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f Future.** versio
2c9d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ns of SQLite may
2c9e0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 change the beha
2c9f0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f vior of sqlite3_
2ca00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a column_type().**
2ca10 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 following a typ
2ca20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a e conversion..**
2ca30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2ca40 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2ca50 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 UTF-8 string the
2ca60 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
2ca70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
2ca80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2ca90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2caa0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 tes in that BLOB
2cab0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e or string..** ^
2cac0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
2cad0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
2cae0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2caf0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f olumn_bytes() co
2cb00 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
2cb10 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e ring to UTF-8 an
2cb20 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
2cb30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2cb40 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 es..** ^If the r
2cb50 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
2cb60 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
2cb70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2cb80 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 es() uses.** [sq
2cb90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
2cba0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 ] to convert tha
2cbb0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 t value to a UTF
2cbc0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 -8 string and re
2cbd0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
2cbe0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2cbf0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
2cc00 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2cc10 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c s NULL, then sql
2cc20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2cc30 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f s() returns zero
2cc40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2cc50 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
2cc60 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e or UTF-16 strin
2cc70 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
2cc80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2cc90 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 6().** routine r
2cca0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2ccb0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2ccc0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
2ccd0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
2cce0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 sult is a UTF-8
2ccf0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
2cd00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2cd10 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a s16() converts.*
2cd20 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
2cd30 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 UTF-16 and then
2cd40 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2cd50 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 er of bytes..**
2cd60 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2cd70 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 s a numeric valu
2cd80 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 e then sqlite3_c
2cd90 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2cda0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
2cdb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
2cdc0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
2cdd0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 ue to a UTF-16 s
2cde0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2cdf0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2ce00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2ce10 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2ce20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2ce30 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2ce40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2ce50 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
2ce60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 **.** ^The value
2ce70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
2ce80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2ce90 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b tes()] and .** [
2cea0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2ceb0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 ytes16()] do not
2cec0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 include the zer
2ced0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 o terminators at
2cee0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 the end.** of t
2cef0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 he string. ^For
2cf00 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 clarity: the va
2cf10 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
2cf20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2cf30 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 umn_bytes()] and
2cf40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2cf50 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 _bytes16()] are
2cf60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
2cf70 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
2cf80 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 ring, not the nu
2cf90 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
2cfa0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e rs..**.** ^Strin
2cfb0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 gs returned by s
2cfc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2cfd0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 xt() and sqlite3
2cfe0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2cff0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 ,.** even empty
2d000 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 strings, are alw
2d010 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
2d020 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ted. ^The retur
2d030 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 n.** value from
2d040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2d050 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f lob() for a zero
2d060 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 -length BLOB is
2d070 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
2d080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 **.** ^The objec
2d090 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
2d0a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2d0b0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
2d0c0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
2d0d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2d0e0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 ct. An unprotec
2d0f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2d100 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 e object.** may
2d110 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
2d120 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f h [sqlite3_bind_
2d130 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
2d140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
2d150 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
2d160 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2d170 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2d180 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
2d190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2d1a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
2d1b0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
2d1c0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
2d1d0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
2d1e0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
2d1f0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
2d200 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2d210 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
2d220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
2d230 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 tes()], then the
2d240 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2d250 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
2d260 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
2d270 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
2d280 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
2d290 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 appropriate. ^F
2d2a0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 or.** example, i
2d2b0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 f the internal r
2d2c0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 epresentation is
2d2d0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 FLOAT and a tex
2d2e0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 t result.** is r
2d2f0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 equested, [sqlit
2d300 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 e3_snprintf()] i
2d310 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c s used internall
2d320 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 y to perform the
2d330 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 .** conversion a
2d340 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e utomatically. ^
2d350 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 (The following t
2d360 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 able details the
2d370 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 conversions.**
2d380 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 that are applied
2d390 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
2d3a0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
2d3b0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
2d3c0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c r><th> Internal<
2d3d0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 br>Type <th> Req
2d3e0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c uested<br>Type <
2d3f0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a th> Conversion.
2d400 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 **.** <tr><td>
2d410 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 NULL <td> INT
2d420 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 EGER <td> Resu
2d430 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c lt is 0.** <tr><
2d440 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
2d450 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2d460 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a Result is 0.0.*
2d470 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2d480 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
2d490 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2d4a0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
2d4b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2d4c0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
2d4d0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2d4e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
2d4f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2d500 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
2d510 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2d520 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
2d530 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2d540 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2d550 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
2d560 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
2d570 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
2d580 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2d590 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
2d5a0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
2d5b0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
2d5c0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2d5d0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2d5e0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
2d5f0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 om float to inte
2d600 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
2d610 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
2d620 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
2d630 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
2d640 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
2d650 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
2d660 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
2d670 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 d> Same as FLOAT
2d680 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
2d690 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2d6a0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2d6b0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 Use atoi().** <t
2d6c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2d6d0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2d6e0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a td> Use atof().*
2d6f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2d700 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
2d710 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
2d720 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
2d730 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
2d740 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 GER <td> Conve
2d750 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
2d760 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 use atoi().** <t
2d770 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
2d780 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2d790 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
2d7a0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
2d7b0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 f().** <tr><td>
2d7c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
2d7d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
2d7e0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
2d7f0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
2d800 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
2d810 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
2d820 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 * The table abov
2d830 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 e makes referenc
2d840 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 e to standard C
2d850 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e library function
2d860 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 s atoi().** and
2d870 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 atof(). SQLite
2d880 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 does not really
2d890 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 use these functi
2d8a0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 ons. It has its
2d8b0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 .** own equivale
2d8c0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 nt internal rout
2d8d0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 ines. The atoi(
2d8e0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d ) and atof() nam
2d8f0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 es are.** used i
2d900 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 n the table for
2d910 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 brevity and beca
2d920 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d use they are fam
2d930 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a iliar to most.**
2d940 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a C programmers..
2d950 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2d960 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 when type conver
2d970 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 sions occur, poi
2d980 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 nters returned b
2d990 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 y prior.** calls
2d9a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2d9b0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 mn_blob(), sqlit
2d9c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2d9d0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 , and/or.** sqli
2d9e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2d9f0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 6() may be inval
2da00 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 idated..** Type
2da10 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 conversions and
2da20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 pointer invalida
2da30 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 tions might occu
2da40 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c r.** in the foll
2da50 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a owing cases:.**.
2da60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
2da70 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2da80 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e ent is a BLOB an
2da90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2daa0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 _text() or.**
2dab0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
2dac0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
2dad0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 lled. A zero-te
2dae0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a rminator might.*
2daf0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 * need to b
2db00 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 e added to the s
2db10 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c tring.</li>.** <
2db20 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2db30 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 content is UTF-8
2db40 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
2db50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2db60 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2db70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2db80 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2db90 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
2dba0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
2dbb0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 ** to UTF-1
2dbc0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 6.</li>.** <li>
2dbd0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2dbe0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 ent is UTF-16 te
2dbf0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
2dc00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
2dc10 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2dc20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 _column_text() i
2dc30 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
2dc40 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
2dc50 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
2dc60 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a to UTF-8.</li>.
2dc70 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e ** </ul>.**.** ^
2dc80 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 Conversions betw
2dc90 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 een UTF-16be and
2dca0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c UTF-16le are al
2dcb0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 ways done in pla
2dcc0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 ce and do.** not
2dcd0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 invalidate a pr
2dce0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f ior pointer, tho
2dcf0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
2dd00 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2dd10 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
2dd20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 the prior pointe
2dd30 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c r references wil
2dd40 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 l have been modi
2dd50 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e fied. Other kin
2dd60 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 ds.** of convers
2dd70 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 ion are done in
2dd80 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 place when it is
2dd90 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 possible, but s
2dda0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a ometimes they.**
2ddb0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c are not possibl
2ddc0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 e and in those c
2ddd0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 ases prior point
2dde0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 ers are invalida
2ddf0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ted..**.** The s
2de00 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 afest and easies
2de10 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f t to remember po
2de20 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b licy is to invok
2de30 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
2de40 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 .** in one of th
2de50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 e following ways
2de60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
2de70 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2de80 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f umn_text() follo
2de90 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
2dea0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
2deb0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
2dec0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2ded0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
2dee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2def0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
2df00 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2df10 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 text16() followe
2df20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2df30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c umn_bytes16()</l
2df40 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
2df50 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
2df60 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c , you should cal
2df70 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e l sqlite3_column
2df80 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 _text(),.** sqli
2df90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2dfa0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f ), or sqlite3_co
2dfb0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 lumn_text16() fi
2dfc0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 rst to force the
2dfd0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 result.** into
2dfe0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d the desired form
2dff0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 at, then invoke
2e000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2e010 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c ytes() or.** sql
2e020 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2e030 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 s16() to find th
2e040 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 e size of the re
2e050 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 sult. Do not mi
2e060 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 x calls.** to sq
2e070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2e080 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 t() or sqlite3_c
2e090 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 olumn_blob() wit
2e0a0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 h calls to.** sq
2e0b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2e0c0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e es16(), and do n
2e0d0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 ot mix calls to
2e0e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2e0f0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 ext16().** with
2e100 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2e110 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e _column_bytes().
2e120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e .**.** ^The poin
2e130 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 ters returned ar
2e140 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 e valid until a
2e150 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 type conversion
2e160 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 occurs as.** des
2e170 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 cribed above, or
2e180 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f until [sqlite3_
2e190 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
2e1a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
2e1b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
2e1c0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 lize()] is calle
2e1d0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 d. ^The memory
2e1e0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f space used to ho
2e1f0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e ld strings.** an
2e200 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 d BLOBs is freed
2e210 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
2e220 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 Do <b>not</b> p
2e230 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 ass the pointers
2e240 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 returned.** [sq
2e250 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2e260 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
2e270 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
2e280 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
2e290 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
2e2a0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
2e2b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2e2c0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2e2d0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
2e2e0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
2e2f0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
2e300 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
2e310 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
2e320 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
2e330 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
2e340 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
2e350 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2e360 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
2e370 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
2e380 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
2e390 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
2e3a0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
2e3b0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
2e3c0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 MEM].)^.*/.const
2e3d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2e3e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
2e3f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2e400 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
2e410 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
2e420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2e430 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
2e440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2e450 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2e460 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 , int iCol);.dou
2e470 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
2e480 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
2e490 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2e4a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2e4b0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
2e4c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2e4d0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ol);.sqlite3_int
2e4e0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
2e4f0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
2e500 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2e510 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
2e520 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2e530 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
2e540 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2e550 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ol);.const void
2e560 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2e570 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2e580 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2e590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2e5a0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
2e5b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2e5c0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 );.sqlite3_value
2e5d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2e5e0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
2e5f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2e600 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e610 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
2e620 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2e630 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bject.**.** ^The
2e640 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2e650 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
2e660 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
2e670 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2e680 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 tement]..** ^If
2e690 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2e6a0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 evaluation of th
2e6b0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f e statement enco
2e6c0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 untered no error
2e6d0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 s.** or if the s
2e6e0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 tatement is neve
2e6f0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 r been evaluated
2e700 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 , then sqlite3_f
2e710 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e inalize() return
2e720 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 s.** SQLITE_OK.
2e730 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
2e740 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
2e750 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 of statement S f
2e760 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 ailed, then.** s
2e770 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2e780 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 S) returns the a
2e790 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
2e7a0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 r code] or.** [e
2e7b0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
2e7c0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
2e7d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2e7e0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 (S) routine can
2e7f0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
2e800 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a point during.**
2e810 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 the life cycle
2e820 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
2e830 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 tement] S:.** be
2e840 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 fore statement S
2e850 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 is ever evaluat
2e860 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 ed, after.** one
2e870 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 or more calls t
2e880 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
2e890 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e ()], or after an
2e8a0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 y call.** to [sq
2e8b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
2e8c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
2e8d0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 her or not the s
2e8e0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 tatement has.**
2e8f0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 completed execut
2e900 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f ion..**.** ^Invo
2e910 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e king sqlite3_fin
2e920 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c alize() on a NUL
2e930 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
2e940 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
2e950 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
2e960 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 tion must finali
2e970 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 ze every [prepar
2e980 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
2e990 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a order to avoid.
2e9a0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b ** resource leak
2e9b0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 s. It is a grie
2e9c0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 vous error for t
2e9d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
2e9e0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 o try to use.**
2e9f0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2ea00 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
2ea10 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
2ea20 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 . Any use of a
2ea30 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2ea40 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
2ea50 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
2ea60 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 d can result in
2ea70 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a undefined and.**
2ea80 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
2ea90 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 avior such as se
2eaa0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 gfaults and heap
2eab0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
2eac0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
2ead0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
2eae0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2eaf0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2eb00 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
2eb10 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
2eb20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2eb30 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
2eb40 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
2eb50 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
2eb60 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
2eb70 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
2eb80 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
2eb90 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
2eba0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
2ebb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
2ebc0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
2ebd0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
2ebe0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
2ebf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2ec00 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
2ec10 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
2ec20 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
2ec30 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
2ec40 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2ec50 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
2ec60 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
2ec70 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
2ec80 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
2ec90 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
2eca0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ecb0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
2ecc0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
2ecd0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
2ece0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
2ecf0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2ed00 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
2ed10 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
2ed20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ed30 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
2ed40 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
2ed50 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
2ed60 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
2ed70 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
2ed80 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
2ed90 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
2eda0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
2edb0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
2edc0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
2edd0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
2ede0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2edf0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2ee00 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
2ee10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2ee20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
2ee30 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
2ee40 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2ee50 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
2ee60 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
2ee70 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
2ee80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2ee90 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
2eea0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
2eeb0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
2eec0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
2eed0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
2eee0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
2eef0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
2ef00 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
2ef10 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
2ef20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2ef30 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
2ef40 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
2ef50 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
2ef60 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
2ef70 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
2ef80 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
2ef90 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2efa0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2efb0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
2efc0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2efd0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2efe0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions}.**.** ^Th
2eff0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
2f000 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
2f010 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
2f020 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2f030 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
2f040 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
2f050 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2f060 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
2f070 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2f080 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
2f090 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
2f0a0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
2f0b0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
2f0c0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
2f0d0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
2f0e0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
2f0f0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
2f100 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
2f110 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
2f120 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
2f130 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
2f140 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
2f150 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
2f160 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
2f170 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
2f180 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
2f190 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
2f1a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
2f1b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
2f1c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f1d0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
2f1e0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
2f1f0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
2f200 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
2f210 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
2f220 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
2f230 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
2f240 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
2f250 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2f260 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
2f270 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
2f280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f290 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
2f2a0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
2f2b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2f2c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
2f2d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2f2e0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
2f2f0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
2f300 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
2f310 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
2f320 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
2f330 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
2f340 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
2f350 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
2f360 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
2f370 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
2f380 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
2f390 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
2f3a0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
2f3b0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
2f3c0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
2f3d0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
2f3e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
2f3f0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
2f400 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
2f410 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
2f420 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
2f430 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
2f440 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
2f450 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
2f460 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
2f470 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
2f480 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
2f490 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
2f4a0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
2f4b0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
2f4c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
2f4d0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
2f4e0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
2f4f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
2f500 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
2f510 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
2f520 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
2f530 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
2f540 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
2f550 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
2f560 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
2f570 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
2f580 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
2f590 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2f5a0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
2f5b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
2f5c0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
2f5d0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
2f5e0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
2f5f0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
2f600 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
2f610 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
2f620 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
2f630 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 eters. Every SQ
2f640 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
2f650 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 mentation must b
2f660 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a e able to work.*
2f670 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 * with UTF-8, UT
2f680 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 F-16le, or UTF-1
2f690 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6be. But some i
2f6a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
2f6b0 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 ay be.** more ef
2f6c0 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 ficient with one
2f6d0 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 encoding than a
2f6e0 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 nother. ^An app
2f6f0 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 lication may.**
2f700 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
2f710 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
2f720 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 or sqlite3_crea
2f730 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 te_function16()
2f740 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 multiple.** time
2f750 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2f760 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 function but wit
2f770 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 h different valu
2f780 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a es of eTextRep..
2f790 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
2f7a0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f7b0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
2f7c0 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
2f7d0 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
2f7e0 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
2f7f0 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
2f800 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
2f810 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
2f820 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
2f830 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
2f840 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f850 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
2f860 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
2f870 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
2f880 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
2f890 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
2f8a0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
2f8b0 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 NY]..**.** ^(The
2f8c0 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
2f8d0 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
2f8e0 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
2f8f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2f900 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
2f910 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
2f920 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
2f930 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2f940 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a user_data()].)^.
2f950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 **.** ^The sixth
2f960 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 , seventh and ei
2f970 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c ghth parameters,
2f980 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e xFunc, xStep an
2f990 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a d xFinal, are.**
2f9a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c pointers to C-l
2f9b0 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e anguage function
2f9c0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
2f9d0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2f9e0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
2f9f0 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c e. ^A scalar SQL
2fa00 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2fa10 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
2fa20 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e tion of the xFun
2fa30 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e c.** callback on
2fa40 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ly; NULL pointer
2fa50 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 s must be passed
2fa60 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e as the xStep an
2fa70 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 d xFinal.** para
2fa80 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 meters. ^An aggr
2fa90 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
2faa0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
2fab0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2fac0 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 xStep.** and xF
2fad0 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f inal and NULL po
2fae0 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 inter must be pa
2faf0 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
2fb00 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 ^To delete an ex
2fb10 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 isting.** SQL fu
2fb20 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2fb30 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 ate, pass NULL p
2fb40 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 ointers for all
2fb50 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a three function.*
2fb60 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a * callbacks..**.
2fb70 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 ** ^(If the nint
2fb80 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2fb90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2fba0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e nction_v2() is n
2fbb0 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e ot NULL,.** then
2fbc0 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f it is destructo
2fbd0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
2fbe0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
2fbf0 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 er. .** The dest
2fc00 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 ructor is invoke
2fc10 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 d when the funct
2fc20 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 ion is deleted,
2fc30 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a either by being.
2fc40 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 ** overloaded or
2fc50 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
2fc60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
2fc70 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 oses.)^.** ^The
2fc80 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c destructor is al
2fc90 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 so invoked if th
2fca0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c e call to.** sql
2fcb0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2fcc0 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e tion_v2() fails.
2fcd0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 .** ^When the de
2fce0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
2fcf0 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 k of the tenth p
2fd00 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f arameter is invo
2fd10 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 ked, it.** is pa
2fd20 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 ssed a single ar
2fd30 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
2fd40 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 a copy of the ap
2fd50 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a plication data .
2fd60 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 ** pointer which
2fd70 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 was the fifth p
2fd80 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2fd90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
2fda0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 ion_v2()..**.**
2fdb0 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 ^It is permitted
2fdc0 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
2fdd0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2fde0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2fdf0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
2fe00 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
2fe10 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
2fe20 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
2fe30 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
2fe40 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
2fe50 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
2fe60 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c encodings. ^SQL
2fe70 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
2fe80 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
2fe90 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f on that most clo
2fea0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
2feb0 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
2fec0 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
2fed0 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 n is used. ^A f
2fee0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
2fef0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f tation with a no
2ff00 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 n-negative.** nA
2ff10 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rg parameter is
2ff20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 a better match t
2ff30 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 han a function i
2ff40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
2ff50 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 th.** a negative
2ff60 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 nArg. ^A funct
2ff70 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 ion where the pr
2ff80 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
2ff90 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 oding.** matches
2ffa0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
2ffb0 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 coding is a bett
2ffc0 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e er.** match than
2ffd0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
2ffe0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 e the encoding i
2fff0 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a s different. .*
30000 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 * ^A function wh
30010 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
30020 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 difference is b
30030 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 etween UTF16le a
30040 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 nd UTF16be.** is
30050 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 a closer match
30060 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
30070 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
30080 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
30090 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 .** between UTF8
300a0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a and UTF16..**.*
300b0 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 * ^Built-in func
300c0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
300d0 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
300e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
300f0 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
30100 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 .** ^An applicat
30110 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
30120 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
30130 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a d to call other.
30140 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
30150 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 aces. However,
30160 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 such calls must
30170 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 not.** close the
30180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
30190 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a tion nor finaliz
301a0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 e or reset the p
301b0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
301c0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 ment in which th
301d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 e function is ru
301e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 nning..*/.int sq
301f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30200 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 ction(. sqlite3
30210 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
30220 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
30230 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
30240 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
30250 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
30260 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
30270 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
30280 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
30290 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
302a0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
302b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
302c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
302d0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
302e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
302f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
30300 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
30310 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
30320 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
30330 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
30340 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
30350 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
30360 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
30370 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
30380 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
30390 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
303a0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
303b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
303c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
303d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
303e0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
303f0 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 text*).);.int sq
30400 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30410 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ction_v2(. sqli
30420 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
30430 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
30440 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
30450 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
30460 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
30470 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
30480 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
30490 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
304a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
304b0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
304c0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
304d0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
304e0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
304f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
30500 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
30510 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f oy)(void*).);../
30520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
30530 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a ext Encodings.**
30540 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
30550 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
30560 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
30570 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
30580 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
30590 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
305a0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
305b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
305c0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
305d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
305e0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 6LE 2.#de
305f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
30600 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 6BE 3.#de
30610 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
30620 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 6 4
30630 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 /* Use native by
30640 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 te order */.#def
30650 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 ine SQLITE_ANY
30660 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 5 /
30670 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
30680 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a _function only *
30690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
306a0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 _UTF16_ALIGNED
306b0 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 8 /* sqlite3_
306c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
306d0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 only */../*.**
306e0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 CAPI3REF: Deprec
306f0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ated Functions.*
30700 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a * DEPRECATED.**.
30710 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
30720 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 ns are [deprecat
30730 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 ed]. In order t
30740 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 o maintain.** ba
30750 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
30760 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 ility with older
30770 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e code, these fun
30780 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
30790 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 .** to be suppor
307a0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e ted. However, n
307b0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
307c0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 should avoid.**
307d0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 the use of these
307e0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 functions. To
307f0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 help encourage p
30800 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a eople to avoid.*
30810 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 * using these fu
30820 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 nctions, we are
30830 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c not going to tel
30840 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 l you what they
30850 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 do..*/.#ifndef S
30860 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 QLITE_OMIT_DEPRE
30870 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 CATED.SQLITE_DEP
30880 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
30890 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
308a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
308b0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 ext*);.SQLITE_DE
308c0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
308d0 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c ite3_expired(sql
308e0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
308f0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
30900 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
30910 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
30920 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
30930 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
30940 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
30950 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
30960 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
30970 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
30980 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
30990 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
309a0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 id);.SQLITE_DEPR
309b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
309c0 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
309d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
309e0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
309f0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
30a00 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 void*,sq
30a10 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
30a20 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
30a30 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
30a40 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 SQL Function Par
30a50 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a ameter Values.**
30a60 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 .** The C-langua
30a70 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ge implementatio
30a80 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f n of SQL functio
30a90 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
30aa0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 s uses.** this s
30ab0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 et of interface
30ac0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 routines to acce
30ad0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ss the parameter
30ae0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 values on.** th
30af0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 e function or ag
30b00 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 gregate..**.** T
30b10 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 he xFunc (for sc
30b20 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 alar functions)
30b30 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 or xStep (for ag
30b40 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 gregates) parame
30b50 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ters.** to [sqli
30b60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
30b70 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
30b80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
30b90 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 ion16()].** defi
30ba0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 ne callbacks tha
30bb0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
30bc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
30bd0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a d aggregates..**
30be0 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 The 3rd paramet
30bf0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c er to these call
30c00 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 backs is an arra
30c10 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
30c20 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 .** [protected s
30c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
30c40 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 jects. There is
30c50 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 one [sqlite3_va
30c60 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a lue] object for.
30c70 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 ** each paramete
30c80 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e r to the SQL fun
30c90 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f ction. These ro
30ca0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
30cb0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 to.** extract va
30cc0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 lues from the [s
30cd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
30ce0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 jects..**.** The
30cf0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
30d00 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 only with [prot
30d10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
30d20 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
30d30 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
30d40 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e use these routin
30d50 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 es on an [unprot
30d60 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
30d70 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 lue].** object r
30d80 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
30d90 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
30da0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
30db0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
30dc0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
30dd0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 ding [column acc
30de0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a ess functions].*
30df0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 * except that t
30e00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
30e10 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f ke a single [pro
30e20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30e30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
30e40 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 pointer instead
30e50 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 of a [sqlite3_st
30e60 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 mt*] pointer and
30e70 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 an integer colu
30e80 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a mn number..**.**
30e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
30ea0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
30eb0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
30ec0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a a UTF-16 string.
30ed0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ** in the native
30ee0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 byte-order of t
30ef0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e he host machine.
30f00 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
30f10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
30f20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
30f30 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 alue_text16le()
30f40 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 interfaces.** ex
30f50 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 tract UTF-16 str
30f60 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 ings as big-endi
30f70 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e an and little-en
30f80 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c dian respectivel
30f90 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 y..**.** ^(The s
30fa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
30fb0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
30fc0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
30fd0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
30fe0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
30ff0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
31000 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
31010 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
31020 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
31030 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
31040 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
31050 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
31060 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
31070 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
31080 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
31090 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 rmation (in othe
310a0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 r.** words, if t
310b0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 he value is a st
310c0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 ring that looks
310d0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a like a number).*
310e0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 * then the conve
310f0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
31100 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e ed. Otherwise n
31110 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 o conversion occ
31120 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c urs..** The [SQL
31130 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
31140 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
31150 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
31160 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c rned.)^.**.** Pl
31170 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 ease pay particu
31180 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f lar attention to
31190 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 the fact that t
311a0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 he pointer retur
311b0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
311c0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
311d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
311e0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a ue_text()], or.*
311f0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
31200 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 _text16()] can b
31210 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 e invalidated by
31220 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 a subsequent ca
31230 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
31240 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
31250 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
31260 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 _bytes16()], [sq
31270 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
31280 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
31290 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
312a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
312b0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
312c0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
312d0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 e same thread as
312e0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
312f0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 tion that suppli
31300 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ed the [sqlite3_
31310 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 value*] paramete
31320 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 rs..*/.const voi
31330 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
31340 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
31350 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
31360 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 e3_value_bytes(s
31370 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
31380 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
31390 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
313a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 3_value*);.doubl
313b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
313c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 double(sqlite3_v
313d0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
313e0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
313f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 lite3_value*);.s
31400 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
31410 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 ite3_value_int64
31420 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
31430 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
31440 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
31450 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
31460 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
31470 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
31480 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 alue_text16(sqli
31490 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
314a0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
314b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
314c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
314d0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
314e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
314f0 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6be(sqlite3_valu
31500 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
31510 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 _value_type(sqli
31520 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
31530 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
31540 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 umeric_type(sqli
31550 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a te3_value*);../*
31560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
31570 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 tain Aggregate F
31580 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a unction Context.
31590 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 **.** Implementa
315a0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 tions of aggrega
315b0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 te SQL functions
315c0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 use this.** rou
315d0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 tine to allocate
315e0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 memory for stor
315f0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e ing their state.
31600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
31610 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 t time the sqlit
31620 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
31630 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
31640 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 e is called .**
31650 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
31660 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
31670 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 ion, SQLite.** a
31680 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 llocates N of me
31690 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 mory, zeroes out
316a0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e that memory, an
316b0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
316c0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 ter.** to the ne
316d0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 w memory. ^On se
316e0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
316f0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ent calls to.**
31700 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
31710 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 e_context() for
31720 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
31730 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
31740 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d ance,.** the sam
31750 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 e buffer is retu
31760 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 rned. Sqlite3_a
31770 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
31780 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a () is normally.*
31790 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f * called once fo
317a0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f r each invocatio
317b0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 n of the xStep c
317c0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e allback and then
317d0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d one.** last tim
317e0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 e when the xFina
317f0 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e l callback is in
31800 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e voked. ^(When n
31810 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 o rows match.**
31820 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 an aggregate que
31830 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 ry, the xStep()
31840 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 callback of the
31850 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
31860 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 on.** implementa
31870 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 tion is never ca
31880 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 lled and xFinal(
31890 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 ) is called exac
318a0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 tly once..** In
318b0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c those cases, sql
318c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
318d0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 ontext() might b
318e0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 e called for the
318f0 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 .** first time f
31900 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 rom within xFina
31910 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 l().)^.**.** ^Th
31920 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
31930 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
31940 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
31950 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
31960 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 .** when first c
31970 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 alled if N is le
31980 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
31990 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 to zero or if a
319a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
319b0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ate error occurs
319c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d ..**.** ^(The am
319d0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c ount of space al
319e0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
319f0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
31a00 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 text(C,N) is.**
31a10 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 determined by th
31a20 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e e N parameter on
31a30 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 first successfu
31a40 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e l call. Changin
31a50 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f g the.** value o
31a60 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e f N in subsequen
31a70 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
31a80 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
31a90 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 ext() within.**
31aa0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
31ab0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
31ac0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 ance will not re
31ad0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a size the memory.
31ae0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e ** allocation.)^
31af0 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 Within the xFi
31b00 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 nal callback, it
31b10 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f is customary to
31b20 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 set.** N=0 in c
31b30 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
31b40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
31b50 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e t(C,N) so that n
31b60 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 o .** pointless
31b70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
31b80 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 ns occur..**.**
31b90 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 ^SQLite automati
31ba0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 cally frees the
31bb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 memory allocated
31bc0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f by .** sqlite3_
31bd0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
31be0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 t() when the agg
31bf0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e regate query con
31c00 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 cludes..**.** Th
31c10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
31c20 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 r must be a copy
31c30 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
31c40 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 te3_context | SQ
31c50 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 L function conte
31c60 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 xt] that is the
31c70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a first parameter.
31c80 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 ** to the xStep
31c90 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 or xFinal callba
31ca0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 ck routine that
31cb0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 implements the a
31cc0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 ggregate.** func
31cd0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 tion..**.** This
31ce0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
31cf0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
31d00 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
31d10 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 which.** the agg
31d20 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
31d30 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
31d40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
31d50 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
31d60 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
31d70 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 xt*, int nBytes)
31d80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
31d90 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 F: User Data For
31da0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
31db0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 ^The sqlite3_us
31dc0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 er_data() interf
31dd0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
31de0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
31df0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 nter that was th
31e00 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 e pUserData para
31e10 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 meter (the 5th p
31e20 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
31e30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
31e40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
31e50 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
31e60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
31e70 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
31e80 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
31e90 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
31ea0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
31eb0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
31ec0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
31ed0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
31ee0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
31ef0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
31f00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
31f10 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
31f20 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
31f30 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
31f40 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 ser_data(sqlite3
31f50 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
31f60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
31f70 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
31f80 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
31f90 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
31fa0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
31fb0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 dle() interface
31fc0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
31fd0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
31fe0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 to the [databas
31ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 e connection] (t
32000 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 he 1st parameter
32010 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c ).** of the [sql
32020 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
32030 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b tion()].** and [
32040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
32050 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 unction16()] rou
32060 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 tines that origi
32070 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 nally.** registe
32080 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 red the applicat
32090 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
320a0 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 tion..*/.sqlite3
320b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 *sqlite3_contex
320c0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 t_db_handle(sqli
320d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
320e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
320f0 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 Function Auxilia
32100 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 ry Data.**.** Th
32110 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 ese functions ma
32120 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f y be used by (no
32130 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c n-aggregate) SQL
32140 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a functions to.**
32150 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 associate metad
32160 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e ata with argumen
32170 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 t values. If the
32180 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 same value is p
32190 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 assed to.** mult
321a0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 iple invocations
321b0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c of the same SQL
321c0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 function during
321d0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e query execution
321e0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 , under.** some
321f0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 circumstances th
32200 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 e associated met
32210 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 adata may be pre
32220 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d served. An exam
32230 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 ple.** of where
32240 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 this might be us
32250 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 eful is in a reg
32260 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 ular-expression
32270 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 matching.** func
32280 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c tion. The compil
32290 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ed version of th
322a0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
322b0 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 sion can be stor
322c0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
322d0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
322e0 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 h the pattern st
322f0 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 ring. .** Then
32300 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 as long as the p
32310 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 attern string re
32320 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a mains the same,.
32330 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 ** the compiled
32340 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
32350 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 on can be reused
32360 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 on multiple.**
32370 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
32380 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
32390 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
323a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
323b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
323c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
323d0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a o the metadata.*
323e0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 * associated by
323f0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
32400 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 auxdata() functi
32410 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 on with the Nth
32420 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 argument.** valu
32430 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 e to the applica
32440 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
32450 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 ction. ^If there
32460 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a is no metadata.
32470 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
32480 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 th the function
32490 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 argument, this s
324a0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
324b0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a ta() interface.*
324c0 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c * returns a NULL
324d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
324e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 ^The sqlite3_set
324f0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
32500 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 ) interface save
32510 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 s P as metadata
32520 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 for the N-th.**
32530 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 argument of the
32540 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
32550 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e ned function. ^
32560 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 Subsequent.** ca
32570 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 lls to sqlite3_g
32580 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 et_auxdata(C,N)
32590 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 return P from th
325a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a e most recent.**
325b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
325c0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 data(C,N,P,X) ca
325d0 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 ll if the metada
325e0 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 ta is still vali
325f0 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 d or.** NULL if
32600 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 the metadata has
32610 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e been discarded.
32620 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 .** ^After each
32630 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
32640 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
32650 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 P,X) where X is
32660 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c not NULL,.** SQL
32670 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 ite will invoke
32680 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 the destructor f
32690 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 unction X with p
326a0 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 arameter P exact
326b0 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e ly.** once, when
326c0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 the metadata is
326d0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 discarded..** S
326e0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f QLite is free to
326f0 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 discard the met
32700 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d adata at any tim
32710 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 e, including: <u
32720 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 l>.** <li> when
32730 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
32740 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d g function param
32750 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 eter changes, or
32760 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 .** <li> when [s
32770 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
32780 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
32790 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 lize()] is calle
327a0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 d for the.**
327b0 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c SQL statement,
327c0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e or.** <li> when
327d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
327e0 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 data() is invoke
327f0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 d again on the s
32800 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f ame parameter, o
32810 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 r.** <li> during
32820 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 the original sq
32830 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
32840 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 a() call when a
32850 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 memory .**
32860 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
32870 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e occurs. </ul>)^
32880 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 .**.** Note the
32890 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 last bullet in p
328a0 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 articular. The
328b0 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 destructor X in
328c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
328d0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 auxdata(C,N,P,X)
328e0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 might be called
328f0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
32900 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 fore the.** sqli
32910 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
32920 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e ) interface even
32930 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 returns. Hence
32940 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
32950 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 data().** should
32960 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 be called near
32970 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
32980 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
32990 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a tation and the.*
329a0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 * function imple
329b0 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
329c0 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 not make any us
329d0 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 e of P after.**
329e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
329f0 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 ata() has been c
32a00 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 alled..**.** ^(I
32a10 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 n practice, meta
32a20 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 data is preserve
32a30 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 d between functi
32a40 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 on calls for.**
32a50 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
32a60 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d ers that are com
32a70 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 pile-time consta
32a80 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c nts, including l
32a90 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
32aa0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 and [parameters
32ab0 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e ] and expression
32ac0 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 s composed from
32ad0 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a the same.)^.**.*
32ae0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
32af0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
32b00 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
32b10 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
32b20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32b30 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
32b40 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 .void *sqlite3_g
32b50 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
32b60 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
32b70 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 N);.void sqlite
32b80 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_set_auxdata(sq
32b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32ba0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f int N, void*, vo
32bb0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a id (*)(void*));.
32bc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32bd0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 : Constants Defi
32be0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 ning Special Des
32bf0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 tructor Behavior
32c00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
32c10 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 special values
32c20 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 for the destruct
32c30 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 or that is passe
32c40 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
32c50 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f inal argument to
32c60 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
32c70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
32c80 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 lob()]. ^If the
32c90 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
32ca0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
32cb0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
32cc0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
32cd0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
32ce0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
32cf0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
32d00 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
32d10 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
32d20 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 yed. ^The.** SQ
32d30 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 LITE_TRANSIENT v
32d40 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 alue means that
32d50 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c the content will
32d60 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 likely change i
32d70 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 n.** the near fu
32d80 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 ture and that SQ
32d90 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 Lite should make
32da0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
32db0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
32dc0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 content before r
32dd0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
32de0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e The typedef is n
32df0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b ecessary to work
32e00 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 around problems
32e10 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 in certain.** C
32e20 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f ++ compilers..*/
32e30 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
32e40 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
32e50 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
32e60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
32e70 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
32e80 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
32e90 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
32ea0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
32eb0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
32ec0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
32ed0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
32ee0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
32ef0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
32f00 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 Function.**.** T
32f10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
32f20 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 e used by the xF
32f30 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 unc or xFinal ca
32f40 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 llbacks that.**
32f50 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 implement SQL fu
32f60 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
32f70 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 egates. See.**
32f80 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
32f90 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
32fa0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
32fb0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
32fc0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
32fd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
32fe0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
32ff0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 ns work very muc
33000 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 h like the [para
33010 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 meter binding] f
33020 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 amily of.** func
33030 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 tions used to bi
33040 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 nd values to hos
33050 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 t parameters in
33060 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
33070 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f nts..** Refer to
33080 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 the [SQL parame
33090 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ter] documentati
330a0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
330b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
330c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
330d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 3_result_blob()
330e0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
330f0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
33100 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
33110 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
33120 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 n to be the BLOB
33130 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 whose content i
33140 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 s pointed.** to
33150 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 by the second pa
33160 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 rameter and whic
33170 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e h is N bytes lon
33180 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 g where N is the
33190 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
331a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
331b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
331c0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
331d0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
331e0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
331f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
33200 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
33210 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
33220 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
33230 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
33240 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
33250 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
33260 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
33270 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
33280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
33290 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 ouble() interfac
332a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
332b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
332c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
332d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
332e0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
332f0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
33300 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 .** by its 2nd a
33310 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
33320 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33330 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
33340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
33350 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
33360 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
33370 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
33380 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
33390 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
333a0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
333b0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 he string pointe
333c0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 d to by the.** 2
333d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
333e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
333f0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 rror() or sqlite
33400 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
33410 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 ().** as the tex
33420 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 t of an error me
33430 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 ssage. ^SQLite
33440 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
33450 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
33460 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
33470 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33480 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 () as UTF-8. ^SQ
33490 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 Lite.** interpre
334a0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 ts the string fr
334b0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
334c0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 t_error16() as U
334d0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a TF-16 in native.
334e0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 ** byte order.
334f0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
33500 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
33510 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
33520 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
33530 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
33540 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 is negative the
33550 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 n SQLite takes a
33560 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
33570 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 essage all text
33580 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 up through the f
33590 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
335a0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
335b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
335c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
335d0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 t_error() or.**
335e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
335f0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d rror16() is non-
33600 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
33610 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 Lite takes that
33620 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e many.** bytes (n
33630 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 ot characters) f
33640 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
33650 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 meter as the err
33660 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e or message..** ^
33670 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33680 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
33690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
336a0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 ror16().** routi
336b0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 nes make a priva
336c0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 te copy of the e
336d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
336e0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 t before.** they
336f0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c return. Hence,
33700 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
33710 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f ction can deallo
33720 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 cate or.** modif
33730 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 y the text after
33740 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 they return wit
33750 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 hout harm..** ^T
33760 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33770 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 t_error_code() f
33780 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 unction changes
33790 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a the error code.*
337a0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 * returned by SQ
337b0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 Lite as a result
337c0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 of an error in
337d0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 a function. ^By
337e0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 default,.** the
337f0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 error code is S
33800 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 QLITE_ERROR. ^A
33810 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
33820 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
33830 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
33840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33850 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 error16() resets
33860 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
33870 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e to SQLITE_ERROR.
33880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
33890 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
338a0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
338b0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
338c0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
338d0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
338e0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
338f0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c or BLOB is too l
33900 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ong to represent
33910 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33920 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33930 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 r_nomem() interf
33940 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
33950 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
33960 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
33970 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 g that a memory
33980 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 allocation faile
33990 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
339a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
339b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
339c0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
339d0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
339e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
339f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
33a00 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 the 32-bit signe
33a10 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
33a20 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
33a30 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
33a40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
33a50 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 sult_int64() int
33a60 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
33a70 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
33a80 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
33a90 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33aa0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 ion to be the 64
33ab0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
33ac0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
33ad0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
33ae0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
33af0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33b00 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 t_null() interfa
33b10 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
33b20 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
33b30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
33b40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
33b50 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a to be NULL..**.*
33b60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
33b70 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 esult_text(), sq
33b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
33b90 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 t16(),.** sqlite
33ba0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
33bb0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 e(), and sqlite3
33bc0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
33bd0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
33be0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 set the return
33bf0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 value of the app
33c00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
33c10 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a function to be.
33c20 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 ** a text string
33c30 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 which is repres
33c40 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 ented as UTF-8,
33c50 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
33c60 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 te order,.** UTF
33c70 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 -16 little endia
33c80 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
33c90 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 endian, respect
33ca0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 ively..** ^SQLit
33cb0 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 e takes the text
33cc0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 result from the
33cd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f application fro
33ce0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 m.** the 2nd par
33cf0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 ameter of the sq
33d00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
33d10 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a t* interfaces..*
33d20 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 * ^If the 3rd pa
33d30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
33d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
33d50 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
33d60 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
33d70 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
33d80 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
33d90 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
33da0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 ter.** through t
33db0 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
33dc0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 aracter..** ^If
33dd0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
33de0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
33df0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
33e00 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
33e10 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
33e20 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 n as many bytes
33e30 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 (not characters)
33e40 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 of the text.**
33e50 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
33e60 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
33e70 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 are taken as the
33e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33e90 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ined.** function
33ea0 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 result. If the
33eb0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 3rd parameter i
33ec0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
33ed0 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 then it.** must
33ee0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 be the byte offs
33ef0 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 et into the stri
33f00 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c ng where the NUL
33f10 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c terminator woul
33f20 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 d.** appear if t
33f30 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 he string where
33f40 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 NUL terminated.
33f50 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
33f60 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 acters occur.**
33f70 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 in the string at
33f80 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 a byte offset t
33f90 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e hat is less than
33fa0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
33fb0 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 e 3rd.** paramet
33fc0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 er, then the res
33fd0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 ulting string wi
33fe0 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 ll contain embed
33ff0 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 ded NULs and the
34000 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 .** result of ex
34010 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 pressions operat
34020 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 ing on strings w
34030 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ith embedded NUL
34040 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a s is undefined..
34050 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 ** ^If the 4th p
34060 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
34070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
34080 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
34090 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
340a0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e sult_blob is a n
340b0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c on-NULL pointer,
340c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c then SQLite cal
340d0 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 ls that.** funct
340e0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 ion as the destr
340f0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 uctor on the tex
34100 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 t or BLOB result
34110 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 when it has.**
34120 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
34130 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e hat result..** ^
34140 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
34150 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
34160 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
34170 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 interfaces or t
34180 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 o.** sqlite3_res
34190 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 ult_blob is the
341a0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 special constant
341b0 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 SQLITE_STATIC,
341c0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 then SQLite.** a
341d0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 ssumes that the
341e0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
341f0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 ult is in consta
34200 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 nt space and doe
34210 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 s not.** copy th
34220 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
34230 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 parameter nor c
34240 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 all a destructor
34250 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a on the content.
34260 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 ** when it has f
34270 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
34280 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 at result..** ^I
34290 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
342a0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
342b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
342c0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
342d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
342e0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 blob is the spec
342f0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c ial constant SQL
34300 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a ITE_TRANSIENT.**
34310 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b then SQLite mak
34320 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
34330 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 result into spa
34340 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ce obtained from
34350 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
34360 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 3_malloc()] befo
34370 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a re it returns..*
34380 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34390 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
343a0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
343b0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
343c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
343d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
343e0 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 n to be a copy t
343f0 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 he.** [unprotect
34400 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
34410 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 ] object specifi
34420 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 ed by the 2nd pa
34430 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a rameter. ^The.*
34440 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
34450 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
34460 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 ce makes a copy
34470 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
34480 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 value].** so tha
34490 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 t the [sqlite3_v
344a0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 alue] specified
344b0 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 in the parameter
344c0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a may change or.*
344d0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 * be deallocated
344e0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 after sqlite3_r
344f0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 esult_value() re
34500 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 turns without ha
34510 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 rm..** ^A [prote
34520 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
34530 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 ue] object may a
34540 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 lways be used wh
34550 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f ere an.** [unpro
34560 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
34570 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 alue] object is
34580 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 required, so eit
34590 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b her.** kind of [
345a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
345b0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 bject can be use
345c0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 d with this inte
345d0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rface..**.** If
345e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
345f0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 re called from w
34600 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 ithin the differ
34610 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 ent thread.** th
34620 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 an the one conta
34630 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 ining the applic
34640 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34650 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 nction that rece
34660 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c ived.** the [sql
34670 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f ite3_context] po
34680 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c inter, the resul
34690 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
346a0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
346b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
346c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
346d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
346e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
346f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
34700 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
34710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
34720 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 double);.void sq
34730 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
34740 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 or(sqlite3_conte
34750 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
34760 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
34770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
34780 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r16(sqlite3_cont
34790 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
347a0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
347b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
347c0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 or_toobig(sqlite
347d0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
347e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
347f0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
34800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
34810 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
34820 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
34830 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
34840 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
34850 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
34860 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
34870 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
34880 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
34890 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
348a0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
348b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
348c0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
348d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
348e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
348f0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
34900 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
34910 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
34920 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
34930 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34940 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
34950 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
34960 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
34970 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
34980 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34990 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
349a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
349b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
349c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
349d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
349e0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 t_text16be(sqlit
349f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
34a00 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
34a10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
34a20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
34a30 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 lt_value(sqlite3
34a40 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
34a50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 e3_value*);.void
34a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34a70 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
34a80 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
34a90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34aa0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 EF: Define New C
34ab0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 ollating Sequenc
34ac0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 es.**.** ^These
34ad0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 functions add, r
34ae0 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 emove, or modify
34af0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 a [collation] a
34b00 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
34b10 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
34b20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
34b30 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 ified as the fir
34b40 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
34b50 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
34b60 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 the collation is
34b70 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a a UTF-8 string.
34b80 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
34b90 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
34ba0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 ) and sqlite3_cr
34bb0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
34bc0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2().** and a UTF
34bd0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 -16 string in na
34be0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
34bf0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
34c00 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
34c10 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 ..** ^Collation
34c20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 names that compa
34c30 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 re equal accordi
34c40 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ng to [sqlite3_s
34c50 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a trnicmp()] are.*
34c60 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 * considered to
34c70 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 be the same name
34c80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 ..**.** ^(The th
34c90 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 ird argument (eT
34ca0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 extRep) must be
34cb0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 one of the const
34cc0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ants:.** <ul>.**
34cd0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
34ce0 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 F8],.** <li> [SQ
34cf0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a LITE_UTF16LE],.*
34d00 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 * <li> [SQLITE_U
34d10 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e TF16BE],.** <li>
34d20 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c [SQLITE_UTF16],
34d30 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c or.** <li> [SQL
34d40 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
34d50 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a D]..** </ul>)^.*
34d60 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 * ^The eTextRep
34d70 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 argument determi
34d80 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 nes the encoding
34d90 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 of strings pass
34da0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c ed.** to the col
34db0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
34dc0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 callback, xCallb
34dd0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ack..** ^The [SQ
34de0 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 LITE_UTF16] and
34df0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c [SQLITE_UTF16_AL
34e00 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f IGNED] values fo
34e10 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f r eTextRep.** fo
34e20 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 rce strings to b
34e30 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 e UTF16 with nat
34e40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
34e50 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
34e60 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 UTF16_ALIGNED] v
34e70 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 alue for eTextRe
34e80 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 p forces strings
34e90 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 to begin.** on
34ea0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 an even byte add
34eb0 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ress..**.** ^The
34ec0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
34ed0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 , pArg, is an ap
34ee0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
34ef0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 ointer that is p
34f00 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 assed.** through
34f10 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
34f20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f gument to the co
34f30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
34f40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
34f50 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 ^The fifth argu
34f60 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c ment, xCallback,
34f70 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
34f80 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
34f90 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c unction..** ^Mul
34fa0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 tiple collating
34fb0 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 functions can be
34fc0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e registered usin
34fd0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 g the same name
34fe0 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 but.** with diff
34ff0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 erent eTextRep p
35000 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 arameters and SQ
35010 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 Lite will use wh
35020 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 ichever.** funct
35030 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 ion requires the
35040 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
35050 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 data transforma
35060 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 tion..** ^If the
35070 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d xCallback argum
35080 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e ent is NULL then
35090 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
350a0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 unction is.** de
350b0 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c leted. ^When al
350c0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 l collating func
350d0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 tions having the
350e0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 same name are d
350f0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 eleted,.** that
35100 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 collation is no
35110 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a longer usable..*
35120 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 *.** ^The collat
35130 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c ing function cal
35140 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
35150 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 with a copy of
35160 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 the pArg .** app
35170 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
35180 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 inter and with t
35190 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 wo strings in th
351a0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 e encoding speci
351b0 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 fied.** by the e
351c0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 TextRep argument
351d0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 . The collating
351e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 function must r
351f0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 eturn an.** inte
35200 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 ger that is nega
35210 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 tive, zero, or p
35220 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 ositive.** if th
35230 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 e first string i
35240 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 s less than, equ
35250 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 al to, or greate
35260 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e r than the secon
35270 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 d,.** respective
35280 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 ly. A collating
35290 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 function must a
352a0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 lways return the
352b0 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 same answer.**
352c0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 given the same i
352d0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f nputs. If two o
352e0 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 r more collating
352f0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 functions are r
35300 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 egistered.** to
35310 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 the same collati
35320 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 on name (using d
35330 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 ifferent eTextRe
35340 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 p values) then a
35350 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 ll.** must give
35360 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e an equivalent an
35370 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 swer when invoke
35380 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e d with equivalen
35390 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 t strings..** Th
353a0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
353b0 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 tion must obey t
353c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f he following pro
353d0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a perties for all.
353e0 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c ** strings A, B,
353f0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f and C:.**.** <o
35400 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d l>.** <li> If A=
35410 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a =B then B==A..**
35420 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e <li> If A==B an
35430 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 d B==C then A==C
35440 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c ..** <li> If A&l
35450 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e t;B THEN B>A.
35460 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 .** <li> If A<
35470 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 ;B and B<C th
35480 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f en A<C..** </
35490 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 ol>.**.** If a c
354a0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
354b0 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 n fails any of t
354c0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 he above constra
354d0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a ints and that.**
354e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
354f0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 ion is register
35500 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 ed and used, the
35510 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
35520 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 f SQLite.** is u
35530 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
35540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 ^The sqlite3_cre
35550 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
35560 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 () works like sq
35570 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
35580 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 lation().** with
35590 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 the addition th
355a0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 at the xDestroy
355b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
355c0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e ked on pArg when
355d0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e .** the collatin
355e0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 g function is de
355f0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 leted..** ^Colla
35600 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 ting functions a
35610 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 re deleted when
35620 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 they are overrid
35630 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 den by later.**
35640 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c calls to the col
35650 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 lation creation
35660 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 functions or whe
35670 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 n the.** [databa
35680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
35690 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b s closed using [
356a0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
356b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 ..**.** ^The xDe
356c0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 stroy callback i
356d0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c s <u>not</u> cal
356e0 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 led if the .** s
356f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
35700 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e llation_v2() fun
35710 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 ction fails. Ap
35720 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
35730 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
35740 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
35750 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e on_v2() with a n
35760 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 on-NULL xDestroy
35770 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
35780 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 .** check the r
35790 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 eturn code and d
357a0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 ispose of the ap
357b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
357c0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 ointer.** themse
357d0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e lves rather than
357e0 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 expecting SQLit
357f0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 e to deal with i
35800 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 t for them..** T
35810 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 his is different
35820 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 from every othe
35830 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
35840 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 ce. The inconsi
35850 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e stency .** is un
35860 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 fortunate but ca
35870 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 nnot be changed
35880 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
35890 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 backwards .** c
358a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
358b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b .** See also: [
358c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
358d0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 n_needed()] and
358e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 [sqlite3_collati
358f0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a on_needed16()]..
35900 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
35910 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
35920 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
35930 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
35940 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
35950 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 ep, . void *pAr
35960 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 g,. int(*xCompa
35970 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
35980 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
35990 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e nst void*).);.in
359a0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
359b0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
359c0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
359d0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
359e0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
359f0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
35a00 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
35a10 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
35a20 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
35a30 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
35a40 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
35a50 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
35a60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
35a70 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
35a80 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
35a90 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
35aa0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 extRep, . void
35ab0 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 *pArg,. int(*xC
35ac0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
35ad0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
35ae0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
35af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
35b00 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 F: Collation Nee
35b10 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ded Callbacks.**
35b20 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 .** ^To avoid ha
35b30 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 ving to register
35b40 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 all collation s
35b50 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 equences before
35b60 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 a database.** ca
35b70 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e n be used, a sin
35b80 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e gle callback fun
35b90 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
35ba0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 istered with the
35bb0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
35bc0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 nnection] to be
35bd0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
35be0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f an undefined co
35bf0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
35c00 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e nce is required.
35c10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
35c20 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 unction is regis
35c30 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
35c40 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
35c50 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a n_needed() API,.
35c60 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 ** then it is pa
35c70 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f ssed the names o
35c80 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c f undefined coll
35c90 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
35ca0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e as strings.** en
35cb0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 coded in UTF-8.
35cc0 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c ^If sqlite3_coll
35cd0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
35ce0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 is used,.** the
35cf0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 names are passe
35d00 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d d as UTF-16 in m
35d10 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 achine native by
35d20 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 te order..** ^A
35d30 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 call to either f
35d40 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 unction replaces
35d50 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f the existing co
35d60 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 llation-needed c
35d70 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
35d80 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 (When the callba
35d90 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
35da0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
35db0 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
35dc0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
35dd0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
35de0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
35df0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
35e00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
35e10 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 on_needed16().
35e20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
35e30 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 ent is the datab
35e40 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
35e50 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 n. The third ar
35e60 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
35e70 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
35e80 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
35e90 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
35ea0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 UTF16LE], indica
35eb0 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 ting the most de
35ec0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 sirable form of
35ed0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
35ee0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 sequence functi
35ef0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 on required. Th
35f00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
35f10 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
35f20 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
35f30 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
35f40 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 ence.)^.**.** Th
35f50 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
35f60 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 ion should regis
35f70 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 ter the desired
35f80 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a collation using.
35f90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
35fa0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c te_collation()],
35fb0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
35fc0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c _collation16()],
35fd0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
35fe0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
35ff0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 _v2()]..*/.int s
36000 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
36010 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 _needed(. sqlit
36020 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a e3*, . void*, .
36030 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
36040 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
36050 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 xtRep,const char
36060 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
36070 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
36080 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a ed16(. sqlite3*
36090 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f , . void*,. vo
360a0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
360b0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
360c0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 p,const void*).)
360d0 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 ;..#ifdef SQLITE
360e0 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a _HAS_CODEC./*.**
360f0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 Specify the key
36100 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 for an encrypte
36110 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 d database. Thi
36120 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 s routine should
36130 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 be.** called ri
36140 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 ght after sqlite
36150 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_open()..**.**
36160 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
36170 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
36180 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
36190 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
361a0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
361b0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 te..*/.int sqlit
361c0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 e3_key(. sqlite
361d0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
361e0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
361f0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
36200 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
36210 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
36220 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
36230 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 y */.);.int sqli
36240 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 te3_key_v2(. sq
36250 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
36260 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
36270 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
36280 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
36290 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c t char *zDbName,
362a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 /* Na
362b0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
362c0 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f se */. const vo
362d0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
362e0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
362f0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
36300 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e hange the key on
36310 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
36320 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 e. If the curre
36330 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e nt database is n
36340 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c ot.** encrypted,
36350 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
36360 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 ll encrypt it.
36370 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e If pNew==0 or nN
36380 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 ew==0, the.** da
36390 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 tabase is decryp
363a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ted..**.** The c
363b0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
363c0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
363d0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
363e0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
363f0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
36400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
36410 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
36420 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
36430 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
36440 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
36450 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
36460 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
36470 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b /* The new k
36480 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ey */.);.int sql
36490 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20 ite3_rekey_v2(.
364a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
364b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
364c0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
364d0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
364e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
364f0 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a me, /*
36500 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 Name of the dat
36510 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
36520 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
36530 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
36540 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a new key */.);..
36550 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 /*.** Specify th
36560 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 e activation key
36570 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 for a SEE datab
36580 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a ase. Unless .**
36590 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 activated, none
365a0 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 of the SEE rout
365b0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a ines will work..
365c0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
365d0 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 activate_see(.
365e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 const char *zPas
365f0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f sPhrase /
36600 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 * Activation phr
36610 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 ase */.);.#endif
36620 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f ..#ifdef SQLITE_
36630 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a ENABLE_CEROD./*.
36640 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 ** Specify the a
36650 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f ctivation key fo
36660 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 r a CEROD databa
36670 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 se. Unless .**
36680 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 activated, none
36690 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 of the CEROD rou
366a0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e tines will work.
366b0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
366c0 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 _activate_cerod(
366d0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
366e0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 PassPhrase
366f0 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 /* Activation
36700 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e phrase */.);.#en
36710 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
36720 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
36730 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
36740 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 rt Time.**.** Th
36750 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 e sqlite3_sleep(
36760 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 ) function cause
36770 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 s the current th
36780 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 read to suspend
36790 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 execution.** for
367a0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 at least a numb
367b0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
367c0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ds specified in
367d0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a its parameter..*
367e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 *.** If the oper
367f0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
36800 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
36810 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
36820 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
36830 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
36840 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
36850 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
36860 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
36870 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 rest second. The
36880 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
36890 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
368a0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 actually.** req
368b0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 uested from the
368c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
368d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
368e0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c .** ^SQLite impl
368f0 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 ements this inte
36900 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 rface by calling
36910 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a the xSleep().**
36920 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 method of the d
36930 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
36940 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 vfs] object. If
36950 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 the xSleep() me
36960 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 thod.** of the d
36970 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f efault VFS is no
36980 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f t implemented co
36990 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 rrectly, or not
369a0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a implemented at.*
369b0 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 * all, then the
369c0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
369d0 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 te3_sleep() may
369e0 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 deviate from the
369f0 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 description.**
36a00 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
36a10 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 paragraphs..*/.i
36a20 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 nt sqlite3_sleep
36a30 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
36a40 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
36a50 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
36a60 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c ng Temporary Fil
36a70 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 es.**.** ^(If th
36a80 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 is global variab
36a90 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f le is made to po
36aa0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
36ab0 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 which is.** the
36ac0 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 name of a folder
36ad0 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f (a.k.a. directo
36ae0 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 ry), then all te
36af0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a mporary files.**
36b00 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 created by SQLi
36b10 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 te when using a
36b20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 built-in [sqlite
36b30 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 3_vfs | VFS].**
36b40 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 will be placed i
36b50 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 n that directory
36b60 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 .)^ ^If this va
36b70 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e riable.** is a N
36b80 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
36b90 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d n SQLite perform
36ba0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 s a search for a
36bb0 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a n appropriate.**
36bc0 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 temporary file
36bd0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
36be0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
36bf0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
36c00 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
36c10 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 in more than one
36c20 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 .** thread at a
36c30 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 time. It is not
36c40 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 safe to read or
36c50 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 modify this var
36c60 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 iable.** if a [d
36c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
36c80 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 on] is being use
36c90 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 d at the same ti
36ca0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 me in a separate
36cb0 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 .** thread..** I
36cc0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 t is intended th
36cd0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
36ce0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 be set once.**
36cf0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 as part of proce
36d00 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
36d10 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 n and before any
36d20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
36d30 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 e.** routines ha
36d40 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 ve been called a
36d50 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 nd that this var
36d60 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 iable remain unc
36d70 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 hanged.** therea
36d80 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 fter..**.** ^The
36d90 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
36da0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d ectory pragma] m
36db0 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 ay modify this v
36dc0 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 ariable and caus
36dd0 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 e.** it to point
36de0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
36df0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
36e00 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 3_malloc]. ^Fur
36e10 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 thermore,.** the
36e20 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
36e30 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 ectory pragma] a
36e40 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 lways assumes th
36e50 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a at any string.**
36e60 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
36e70 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 ble points to is
36e80 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 held in memory
36e90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a obtained from .*
36ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
36eb0 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d c] and the pragm
36ec0 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f a may attempt to
36ed0 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 free that memor
36ee0 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 y.** using [sqli
36ef0 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 te3_free]..** He
36f00 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 nce, if this var
36f10 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 iable is modifie
36f20 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 d directly, eith
36f30 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a er it should be.
36f40 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 ** made NULL or
36f50 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
36f60 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
36f70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
36f80 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 alloc].** or els
36f90 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 e the use of the
36fa0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
36fb0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 ectory pragma] s
36fc0 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 hould be avoided
36fd0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
36fe0 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
36ff0 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
37000 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
37010 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
37020 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
37030 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
37040 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 open] or [sqlite
37050 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 3_open_v2]. Oth
37060 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
37070 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
37080 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
37090 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
370a0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 les may fail. H
370b0 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 ere is an.** exa
370c0 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 mple of how to d
370d0 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b o this using C++
370e0 20 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 with the Window
370f0 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a s Runtime:.**.**
37100 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
37110 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 e>.** LPCWSTR zP
37120 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 ath = Windows::S
37130 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 torage::Applicat
37140 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 ionData::Current
37150 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 ->.**
37160 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 TemporaryFolder
37170 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a ->Path->Data();.
37180 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 ** char zPathBuf
37190 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 [MAX_PATH +
371a0 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 1];.** memse
371b0 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 t(zPathBuf, 0, s
371c0 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 izeof(zPathBuf))
371d0 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d ;.** WideCharToM
371e0 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 ultiByte(CP_UTF8
371f0 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 , 0, zPath, -1,
37200 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 zPathBuf, sizeof
37210 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 (zPathBuf),.** &
37220 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 nbsp; NULL,
37230 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 NULL);.** sqlite
37240 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
37250 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
37260 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 tf("%s", zPathBu
37270 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 f);.** </pre></b
37280 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 lockquote>.*/.SQ
37290 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 LITE_EXTERN char
372a0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 *sqlite3_temp_d
372b0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a irectory;../*.**
372c0 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
372d0 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f Of The Folder Ho
372e0 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 lding Database F
372f0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 iles.**.** ^(If
37300 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 this global vari
37310 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 able is made to
37320 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
37330 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 g which is.** th
37340 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 e name of a fold
37350 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 er (a.k.a. direc
37360 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 tory), then all
37370 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a database files.*
37380 2a 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68 * specified with
37390 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
373a0 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64 name and created
373b0 20 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a or accessed by.
373c0 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 ** SQLite when u
373d0 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 sing a built-in
373e0 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 windows [sqlite3
373f0 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c _vfs | VFS] will
37400 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 be assumed.** t
37410 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f o be relative to
37420 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e that directory.
37430 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 )^ ^If this vari
37440 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a able is a NULL.*
37450 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 * pointer, then
37460 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 SQLite assumes t
37470 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 hat all database
37480 20 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64 files specified
37490 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74 .** with a relat
374a0 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65 ive pathname are
374b0 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65 relative to the
374c0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
374d0 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 ry.** for the pr
374e0 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 ocess. Only the
374f0 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b windows VFS mak
37500 65 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67 es use of this g
37510 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c lobal.** variabl
37520 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64 e; it is ignored
37530 20 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53 by the unix VFS
37540 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 ..**.** Changing
37550 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
37560 69 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c is variable whil
37570 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e e a database con
37580 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 nection is.** op
37590 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e en can result in
375a0 20 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62 a corrupt datab
375b0 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 ase..**.** It is
375c0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 not safe to rea
375d0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 d or modify this
375e0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 variable in mor
375f0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 e than one.** th
37600 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 read at a time.
37610 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
37620 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
37630 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a y this variable.
37640 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 ** if a [databas
37650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 e connection] is
37660 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 being used at t
37670 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 he same time in
37680 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 a separate.** th
37690 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 read..** It is i
376a0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 ntended that thi
376b0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 s variable be se
376c0 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 t once.** as par
376d0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 t of process ini
376e0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 tialization and
376f0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 before any SQLit
37700 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 e interface.** r
37710 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 outines have bee
37720 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 n called and tha
37730 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
37740 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 remain unchanged
37750 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a .** thereafter..
37760 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 **.** ^The [data
37770 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
37780 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 pragma] may mod
37790 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
377a0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 e and cause.** i
377b0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 t to point to me
377c0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
377d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
377e0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f oc]. ^Furthermo
377f0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 re,.** the [data
37800 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
37810 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 pragma] always
37820 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 assumes that any
37830 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 string.** that
37840 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f this variable po
37850 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 ints to is held
37860 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e in memory obtain
37870 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c ed from .** [sql
37880 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 ite3_malloc] and
37890 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 the pragma may
378a0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 attempt to free
378b0 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 that memory.** u
378c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 sing [sqlite3_fr
378d0 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 ee]..** Hence, i
378e0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 f this variable
378f0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 is modified dire
37900 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 ctly, either it
37910 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 should be.** mad
37920 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 e NULL or made t
37930 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
37940 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
37950 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
37960 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 .** or else the
37970 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 use of the [data
37980 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
37990 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 pragma] should
379a0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 be avoided..*/.S
379b0 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 QLITE_EXTERN cha
379c0 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f r *sqlite3_data_
379d0 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a directory;../*.*
379e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 * CAPI3REF: Test
379f0 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 For Auto-Commit
37a00 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 Mode.** KEYWORD
37a10 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d S: {autocommit m
37a20 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ode}.**.** ^The
37a30 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f sqlite3_get_auto
37a40 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 commit() interfa
37a50 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ce returns non-z
37a60 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 ero or.** zero i
37a70 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 f the given data
37a80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
37a90 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 is or is not in
37aa0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c autocommit mode,
37ab0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
37ac0 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d . ^Autocommit m
37ad0 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 ode is on by def
37ae0 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f ault..** ^Autoco
37af0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 mmit mode is dis
37b00 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 abled by a [BEGI
37b10 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a N] statement..**
37b20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
37b30 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 e is re-enabled
37b40 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 by a [COMMIT] or
37b50 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a [ROLLBACK]..**.
37b60 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 ** If certain ki
37b70 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 nds of errors oc
37b80 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 cur on a stateme
37b90 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 nt within a mult
37ba0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 i-statement.** t
37bb0 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f ransaction (erro
37bc0 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 rs including [SQ
37bd0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c LITE_FULL], [SQL
37be0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b ITE_IOERR],.** [
37bf0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b SQLITE_NOMEM], [
37c00 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e SQLITE_BUSY], an
37c10 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 d [SQLITE_INTERR
37c20 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a UPT]) then the.*
37c30 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 * transaction mi
37c40 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ght be rolled ba
37c50 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
37c60 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 . The only way
37c70 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 to.** find out w
37c80 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 hether SQLite au
37c90 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
37ca0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e ed back the tran
37cb0 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a saction after.**
37cc0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 an error is to
37cd0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f use this functio
37ce0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 n..**.** If anot
37cf0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 her thread chang
37d00 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 es the autocommi
37d10 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 t status of the
37d20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
37d30 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 ection while thi
37d40 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e s routine is run
37d50 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ning, then the r
37d60 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 eturn value.** i
37d70 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a s undefined..*/.
37d80 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
37d90 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 autocommit(sqlit
37da0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
37db0 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 I3REF: Find The
37dc0 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 Database Handle
37dd0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 Of A Prepared St
37de0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 atement.**.** ^T
37df0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 he sqlite3_db_ha
37e00 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 ndle interface r
37e10 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 eturns the [data
37e20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37e30 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 handle.** to wh
37e40 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 ich a [prepared
37e50 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e statement] belon
37e60 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 gs. ^The [datab
37e70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
37e80 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
37e90 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
37ea0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 is the same [da
37eb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
37ec0 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 n].** that was t
37ed0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
37ee0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c t.** to the [sql
37ef0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
37f00 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 )] call (or its
37f10 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 variants) that w
37f20 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 as used to.** cr
37f30 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 eate the stateme
37f40 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 nt in the first
37f50 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 place..*/.sqlite
37f60 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 3 *sqlite3_db_ha
37f70 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d ndle(sqlite3_stm
37f80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
37f90 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 3REF: Return The
37fa0 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 Filename For A
37fb0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
37fc0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ion.**.** ^The s
37fd0 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 qlite3_db_filena
37fe0 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(D,N) interfac
37ff0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
38000 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d ter to a filenam
38010 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 e.** associated
38020 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 with database N
38030 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e of connection D.
38040 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 ^The main data
38050 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 base file.** has
38060 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 the name "main"
38070 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e . If there is n
38080 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 o attached datab
38090 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 ase N on the dat
380a0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
380b0 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 ion D, or if dat
380c0 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d abase N is a tem
380d0 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d porary or in-mem
380e0 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 ory database, th
380f0 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 en.** a NULL poi
38100 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
38110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c ..**.** ^The fil
38120 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 ename returned b
38130 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 y this function
38140 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 is the output of
38150 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 the.** xFullPat
38160 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 hname method of
38170 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 the [VFS]. ^In
38180 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
38190 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c filename.** wil
381a0 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 l be an absolute
381b0 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 pathname, even
381c0 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 if the filename
381d0 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 used.** to open
381e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 the database ori
381f0 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 ginally was a UR
38200 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 I or relative pa
38210 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 thname..*/.const
38220 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 char *sqlite3_d
38230 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 b_filename(sqlit
38240 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 e3 *db, const ch
38250 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f ar *zDbName);../
38260 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
38270 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 etermine if a da
38280 74 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f tabase is read-o
38290 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nly.**.** ^The s
382a0 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e qlite3_db_readon
382b0 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 ly(D,N) interfac
382c0 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 e returns 1 if t
382d0 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a he database N.**
382e0 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 of connection D
382f0 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 is read-only, 0
38300 20 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 if it is read/w
38310 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e rite, or -1 if N
38320 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e is not.** the n
38330 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 ame of a databas
38340 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e on connection
38350 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 D..*/.int sqlite
38360 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 3_db_readonly(sq
38370 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 lite3 *db, const
38380 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b char *zDbName);
38390 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
383a0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 : Find the next
383b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
383c0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 nt.**.** ^This i
383d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
383e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
383f0 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 e next [prepared
38400 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 statement] afte
38410 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 r.** pStmt assoc
38420 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
38430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
38440 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 ion] pDb. ^If p
38450 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 Stmt is NULL.**
38460 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 then this interf
38470 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
38480 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 inter to the fir
38490 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 st prepared stat
384a0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 ement.** associa
384b0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 ted with the dat
384c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
384d0 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 pDb. ^If no pr
384e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
384f0 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 .** satisfies th
38500 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 e conditions of
38510 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 this routine, it
38520 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a returns NULL..*
38530 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 *.** The [databa
38540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
38550 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 ointer D in a ca
38560 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
38570 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 3_next_stmt(D,S)
38580 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 ] must refer to
38590 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 an open database
385a0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 .** connection a
385b0 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 nd in particular
385c0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e must not be a N
385d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a ULL pointer..*/.
385e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 sqlite3_stmt *sq
385f0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 lite3_next_stmt(
38600 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 sqlite3 *pDb, sq
38610 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
38620 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
38630 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 REF: Commit And
38640 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 Rollback Notific
38650 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a ation Callbacks.
38660 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
38670 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 e3_commit_hook()
38680 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 interface regis
38690 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a ters a callback.
386a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ** function to b
386b0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
386c0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e er a transaction
386d0 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f is [COMMIT | co
386e0 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e mmitted]..** ^An
386f0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 y callback set b
38700 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c y a previous cal
38710 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d l to sqlite3_com
38720 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f mit_hook().** fo
38730 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 r the same datab
38740 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
38750 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
38760 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f ^The sqlite3_ro
38770 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e llback_hook() in
38780 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
38790 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 s a callback.**
387a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
387b0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
387c0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
387d0 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c [ROLLBACK | rol
387e0 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 led back]..** ^A
387f0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 ny callback set
38800 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 by a previous ca
38810 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f ll to sqlite3_ro
38820 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a llback_hook().**
38830 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 for the same da
38840 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase conne