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 4c 4f 43 4b 45 44 5f 53 48 SQLITE_LOCKED_SH
5600: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 AREDCACHE (
5610: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 SQLITE_LOCKED |
5620: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 SQLITE_BUSY_REC
5640: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 OVERY
5650: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c (SQLITE_BUSY |
5660: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
5680: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 N_NOTEMPDIR
5690: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
56a0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 N | (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
56c0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 PEN_ISDIR
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
56e0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 PEN | (2<<8)).#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
5700: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 TOPEN_FULLPATH
5710: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
5720: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a TOPEN | (3<<8)).
5730: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5740: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 ORRUPT_VTAB
5750: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5760: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 ORRUPT | (1<<8))
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5780: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 READONLY_RECOVER
5790: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f Y (SQLITE_
57a0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 READONLY | (1<<8
57b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
57c0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c E_READONLY_CANTL
57d0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 OCK (SQLIT
57e0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c E_READONLY | (2<
57f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5800: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c ITE_READONLY_ROL
5810: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c LBACK (SQL
5820: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
5830: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
5840: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c QLITE_ABORT_ROLL
5850: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 BACK (S
5860: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 QLITE_ABORT | (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 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5890: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 CHECK (SQ
58a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
58b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
58c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
58d0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 INT_COMMITHOOK
58e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
58f0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 INT | (2<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5910: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b STRAINT_FOREIGNK
5920: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e EY (SQLITE_CON
5930: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 STRAINT | (3<<8)
5940: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5950: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 _CONSTRAINT_FUNC
5960: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 TION (SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 _CONSTRAINT | (4
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5990: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
59a0: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 NOTNULL (SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
59c0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
59d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
59e0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 INT_PRIMARYKEY
59f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5a00: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 INT | (6<<8)).#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5a20: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 STRAINT_TRIGGER
5a30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
5a40: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 STRAINT | (7<<8)
5a50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5a60: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 _CONSTRAINT_UNIQ
5a70: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 UE (SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 _CONSTRAINT | (8
5a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5aa0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5ab0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 VTAB (SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5ad0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
5ae0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f e SQLITE_NOTICE_
5af0: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 RECOVER_WAL
5b00: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 (SQLITE_NOTICE
5b10: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5b20: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f e SQLITE_NOTICE_
5b30: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b RECOVER_ROLLBACK
5b40: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 (SQLITE_NOTICE
5b50: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a | (2<<8))../*.**
5b60: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
5b70: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
5b80: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 perations.**.**
5b90: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 These bit values
5ba0: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
5bb0: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 r use in the.**
5bc0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
5bd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
5be0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
5bf0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 ce and.** in the
5c00: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
5c10: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
5c20: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
5c30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5c40: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
5c50: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
5c60: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0001 /* Ok for
5c70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5c80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5c90: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
5ca0: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
5cb0: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0002 /* Ok for
5cc0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5cd0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5ce0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
5cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5d00: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0004 /* Ok for
5d10: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5d20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5d30: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
5d40: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
5d50: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0008 /* VFS onl
5d60: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5d70: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
5d80: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
5d90: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0010 /* VFS onl
5da0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5db0: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f ITE_OPEN_AUTOPRO
5dc0: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 XY 0x0000
5dd0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0020 /* VFS onl
5de0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5df0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 ITE_OPEN_URI
5e00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5e10: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0040 /* Ok for
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5e30: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5e40: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 ITE_OPEN_MEMORY
5e50: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5e60: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0080 /* Ok for
5e70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5e80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5e90: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
5ea0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5eb0: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0100 /* VFS onl
5ec0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5ed0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
5ee0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5ef0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0200 /* VFS onl
5f00: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5f10: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
5f20: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
5f30: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0400 /* VFS onl
5f40: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5f50: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
5f60: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
5f70: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0800 /* VFS onl
5f80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5f90: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
5fa0: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
5fb0: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 1000 /* VFS onl
5fc0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5fd0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
5fe0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
5ff0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 2000 /* VFS onl
6000: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
6010: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
6020: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
6030: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 4000 /* VFS onl
6040: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
6050: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
6060: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6070: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 8000 /* Ok for
6080: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
6090: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
60a0: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
60b0: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 EX 0x0001
60c0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
60e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
60f0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
6100: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 ACHE 0x0002
6110: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
6120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
6130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
6140: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
6150: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 CACHE 0x0004
6160: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
6170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
6180: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
6190: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 ITE_OPEN_WAL
61a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 0x0008
61b0: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0000 /* VFS onl
61c0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 y */../* Reserve
61d0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 d:
61e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 0x00F
61f0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 00000 */../*.**
6200: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
6210: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
6220: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
6230: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
6240: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
6250: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
6260: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
6270: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
6280: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
6290: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 tor of these.**
62a0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
62b0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
62c0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
62d0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
62e0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
62f0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
6300: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
6310: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
6320: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
6330: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6340: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
6350: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
6360: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
6370: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
63a0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
63b0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
63c0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
63d0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
63e0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
63f0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
6400: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
6410: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
6420: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
6430: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6440: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
6450: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
6460: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
6470: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
6480: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
6490: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
64a0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
64b0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
64c0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
64d0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
64e0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
64f0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
6500: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
6510: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
6520: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
6530: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
6540: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
6550: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
6560: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 e(). The SQLITE
6570: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
6580: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 _OVERWRITE prope
6590: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
65a0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 * after reboot f
65b0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 ollowing a crash
65c0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 or power loss,
65d0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 the only bytes i
65e0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 n a.** file that
65f0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 were written at
6600: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
6610: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 level might hav
6620: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 e changed.** and
6630: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 that adjacent b
6640: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 ytes, even bytes
6650: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
6660: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 sector are.** g
6670: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 uaranteed to be
6680: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 unchanged..*/.#d
6690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
66a0: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 AP_ATOMIC
66b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
66c0: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0001.#define SQL
66d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
66e0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 512
66f0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 0x00000002.#def
6700: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6710: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 _ATOMIC1K
6720: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6730: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 04.#define SQLIT
6740: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b E_IOCAP_ATOMIC2K
6750: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6760: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
6770: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6780: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 TOMIC4K
6790: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
67a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 IOCAP_ATOMIC8K
67c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
67d0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 0000020.#define
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
67f0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 MIC16K
6800: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 0x00000040.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 CAP_ATOMIC32K
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6840: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 00080.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6860: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 C64K
6870: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 0x00000100.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6890: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 P_SAFE_APPEND
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
68b0: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 200.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
68d0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 IAL
68e0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 0x00000400.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6900: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e UNDELETABLE_WHEN
6910: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 _OPEN 0x0000080
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
6940: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 _OVERWRITE 0x
6950: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00001000../*.**
6960: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
6970: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a ocking Levels.**
6980: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
6990: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 one of these int
69a0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
69b0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
69c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 ument to calls i
69d0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 t makes to the x
69e0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
69f0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 ck() methods.**
6a00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 of an [sqlite3_i
6a10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
6a20: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t..*/.#define SQ
6a30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 LITE_LOCK_NONE
6a40: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 e SQLITE_LOCK_SH
6a60: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 ARED 1.#d
6a70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6a80: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 K_RESERVED
6a90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
6aa0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 _LOCK_PENDING
6ab0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
6ac0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
6ad0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a IVE 4../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 CAPI3REF: Synch
6af0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 ronization Type
6b00: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e Flags.**.** When
6b10: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
6b20: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
6b30: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
6b40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6b50: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
6b60: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
6b70: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
6b80: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
6b90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
6ba0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
6bb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
6bc0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
6bd0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
6be0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
6bf0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
6c00: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
6c10: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
6c20: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
6c30: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
6c40: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 be flushed. If t
6c50: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
6c60: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a ts of the flag.*
6c70: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 * equal SQLITE_S
6c80: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 YNC_NORMAL, that
6c90: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f means to use no
6ca0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
6cb0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 antics..** If th
6cc0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
6cd0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 s equal SQLITE_S
6ce0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d YNC_FULL, that m
6cf0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d eans.** to use M
6d00: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
6d10: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
6d20: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a f fsync()..**.**
6d30: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 Do not confuse
6d40: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
6d50: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
6d60: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
6d70: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 s.** with the [P
6d80: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
6d90: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 s]=NORMAL and [P
6da0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
6db0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 s]=FULL.** setti
6dc0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 ngs. The [synch
6dd0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 ronous pragma] d
6de0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 etermines when c
6df0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 alls to the.** x
6e00: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 Sync VFS method
6e10: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 occur and applie
6e20: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f s uniformly acro
6e30: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 ss all platforms
6e40: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
6e50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
6e60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
6e70: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 flags determine
6e80: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 how.** energeti
6e90: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 c or rigorous or
6ea0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 forceful the sy
6eb0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 nc operations ar
6ec0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 e and.** only ma
6ed0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 ke a difference
6ee0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 on Mac OSX for t
6ef0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 he default SQLit
6f00: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 e code..** (Thir
6f10: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c d-party VFS impl
6f20: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 ementations migh
6f30: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 t also make the
6f40: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
6f50: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 etween SQLITE_SY
6f60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
6f70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 LITE_SYNC_FULL,
6f80: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a but among the.**
6f90: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
6fa0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 ms natively supp
6fb0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c orted by SQLite,
6fc0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a only Mac OSX.**
6fd0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 cares about the
6fe0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f difference.).*/
6ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7000: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 SYNC_NORMAL
7010: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 0x00002.#defi
7020: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 ne SQLITE_SYNC_F
7030: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 ULL 0x0
7040: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 0003.#define SQL
7050: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
7060: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a Y 0x00010..
7070: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7080: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
7090: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a n File Handle.**
70a0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
70b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
70c0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
70d0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
70e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
70f0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
7100: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
7110: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
7120: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
7130: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
7140: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
7150: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
7160: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
7170: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
7180: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
7190: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
71a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
71b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
71c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
71d0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
71e0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
71f0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
7200: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
7210: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
7220: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
7230: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
7240: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
7250: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
7260: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
7270: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
7280: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
7290: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
72a0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
72b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
72c0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
72d0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
72e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 ject.**.** Every
72f0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 file opened by
7300: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
7310: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 .xOpen] method p
7320: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b opulates an.** [
7330: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7340: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 ject (or, more c
7350: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c ommonly, a subcl
7360: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ass of the.** [s
7370: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7380: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e ect) with a poin
7390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
73a0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
73b0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
73c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 t defines the me
73d0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 thods used to pe
73e0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 rform various op
73f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 erations.** agai
7400: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
7410: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 e represented by
7420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
7430: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a le] object..**.*
7440: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * If the [sqlite
7450: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7460: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c hod sets the sql
7470: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7480: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 ds element .** t
7490: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 o a non-NULL poi
74a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 nter, then the s
74b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
74c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a s.xClose method.
74d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ** may be invoke
74e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 d even if the [s
74f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7500: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 ] reported that
7510: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a it failed. The.
7520: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 ** only way to p
7530: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f revent a call to
7540: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e xClose followin
7550: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 g a failed [sqli
7560: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a te3_vfs.xOpen].*
7570: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 * is for the [sq
7580: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7590: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
75a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
75b0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 s element.** to
75c0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
75d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
75e0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
75f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
7600: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
7610: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
7620: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
7630: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
7640: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
7650: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
7660: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
7670: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
7680: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
7690: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
76a0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
76b0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
76c0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
76d0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
76e0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
76f0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
7700: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
7710: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
7720: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
7730: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
7740: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
7750: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
7760: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
7770: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
7780: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
7790: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
77a0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
77b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
77c0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
77d0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
77e0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
77f0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
7800: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
7810: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
7820: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
7830: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
7840: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
7850: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
7860: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
7870: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
7880: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
7890: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
78a0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
78b0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
78c0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
78d0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
78e0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
78f0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
7900: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
7910: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
7920: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
7930: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
7940: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
7950: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
7960: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
7970: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
7980: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7990: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
79a0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
79b0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
79c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
79d0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
79e0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
79f0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
7a00: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
7a10: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
7a20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
7a30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
7a40: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
7a50: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
7a60: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
7a70: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
7a80: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
7a90: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
7aa0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
7ab0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
7ac0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
7ad0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
7ae0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
7af0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
7b00: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
7b10: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
7b20: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
7b30: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
7b40: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
7b50: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
7b60: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
7b70: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
7b80: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
7b90: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
7ba0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
7bb0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
7bc0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
7bd0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
7be0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c A [SQLITE_FCNTL
7bf0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 _LOCKSTATE | lis
7c00: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
7c10: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
7c20: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
7c30: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
7c40: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
7c50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
7c60: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
7c70: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
7c80: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
7c90: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 id conflicts. V
7ca0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
7cb0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ns should.** ret
7cc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 urn [SQLITE_NOTF
7cd0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 OUND] for file c
7ce0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 ontrol opcodes t
7cf0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
7d00: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a ** recognize..**
7d10: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
7d20: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
7d30: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
7d40: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
7d50: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
7d60: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
7d70: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
7d80: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
7d90: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
7da0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
7db0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
7dc0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
7dd0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
7de0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
7df0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
7e00: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
7e10: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
7e20: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
7e30: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
7e40: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
7e50: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
7e60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7e70: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
7e80: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7e90: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
7ea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7eb0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
7ec0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7ed0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
7ee0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7ef0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
7f00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7f10: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
7f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7f30: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <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 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <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 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
7f80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
7f90: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
7fa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7fb0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
7fc0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
7fd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
7fe0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
7ff0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
8000: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
8010: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
8020: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
8030: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
8040: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
8050: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
8060: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
8070: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
8080: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
8090: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
80a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
80b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
80c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
80d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
80e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
80f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
8100: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
8110: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
8120: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
8130: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
8140: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
8150: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
8160: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
8170: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
8180: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
8190: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
81a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
81b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
81c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
81d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
81e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
81f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
8200: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 ()..**.** If xRe
8210: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c ad() returns SQL
8220: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
8230: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 READ it must als
8240: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 o fill.** in the
8250: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 unread portions
8260: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 of the buffer w
8270: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 ith zeros. A VF
8280: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 S that.** fails
8290: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
82a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 rt reads might s
82b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f eem to work. Ho
82c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 wever,.** failur
82d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 e to zero-fill s
82e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 hort reads will
82f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 eventually lead
8300: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 to.** database c
8310: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 orruption..*/.ty
8320: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
8330: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
8340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8350: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
8360: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a e3_io_methods {.
8370: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
8380: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
8390: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
83a0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 int (*xRead)(s
83b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f qlite3_file*, vo
83c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
83d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
83e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 st);. int (*xWr
83f0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ite)(sqlite3_fil
8400: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c e*, const void*,
8410: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
8420: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
8430: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 . int (*xTrunca
8440: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
8450: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8460: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a size);. int (*
8470: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 xSync)(sqlite3_f
8480: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 ile*, int flags)
8490: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 ;. int (*xFileS
84a0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
84b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
84c0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 4 *pSize);. int
84d0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 (*xLock)(sqlite
84e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
84f0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 int (*xUnlock)(
8500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8510: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 nt);. int (*xCh
8520: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 eckReservedLock)
8530: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8540: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
8550: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 int (*xFileCont
8560: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c rol)(sqlite3_fil
8570: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 e*, int op, void
8580: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *pArg);. int (
8590: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 *xSectorSize)(sq
85a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
85b0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 int (*xDeviceCha
85c0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 racteristics)(sq
85d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
85e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
85f0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
8600: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e ersion 1 */. in
8610: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c t (*xShmMap)(sql
8620: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8630: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 iPg, int pgsz, i
8640: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c nt, void volatil
8650: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 e**);. int (*xS
8660: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f hmLock)(sqlite3_
8670: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 file*, int offse
8680: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c t, int n, int fl
8690: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ags);. void (*x
86a0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 ShmBarrier)(sqli
86b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
86c0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 t (*xShmUnmap)(s
86d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
86e0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 t deleteFlag);.
86f0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
8700: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
8710: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 version 2 */. i
8720: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c nt (*xFetch)(sql
8730: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
8740: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c te3_int64 iOfst,
8750: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 int iAmt, void
8760: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 **pp);. int (*x
8770: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 Unfetch)(sqlite3
8780: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
8790: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 int64 iOfst, voi
87a0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 d *p);. /* Meth
87b0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
87c0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
87d0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 3 */. /* Additi
87e0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
87f0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
8800: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
8810: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
8820: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
8830: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
8840: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e s.**.** These in
8850: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
8860: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 are opcodes for
8870: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
8880: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 method.** of th
8890: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
88a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e thods] object an
88b0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 d for the [sqlit
88c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
88d0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
88e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
88f0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
8900: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
8910: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
8920: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
8930: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
8940: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8950: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
8960: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
8970: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
8980: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
8990: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
89a0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
89b0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
89c0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
89d0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
89e0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
89f0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
8a00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
8a10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
8a20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
8a30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
8a40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
8a50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e g testing and on
8a60: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 ly needs to be s
8a70: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 upported when SQ
8a80: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 LITE_TEST.** is
8a90: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e defined..** <ul>
8aa0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
8ab0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
8ac0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
8ad0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
8ae0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 T] opcode is use
8af0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 d by SQLite to g
8b00: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c ive the VFS.** l
8b10: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 ayer a hint of h
8b20: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 ow large the dat
8b30: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
8b40: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e grow to be durin
8b50: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 g the.** current
8b60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 transaction. T
8b70: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 his hint is not
8b80: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 guaranteed to be
8b90: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 accurate but it
8ba0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f .** is often clo
8bb0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 se. The underly
8bc0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 ing VFS might ch
8bd0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 oose to prealloc
8be0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ate database.**
8bf0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 file space based
8c00: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e on this hint in
8c10: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 order to help w
8c20: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 rites to the dat
8c30: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 abase.** file ru
8c40: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 n faster..**.**
8c50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
8c60: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a TL_CHUNK_SIZE]].
8c70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
8c80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
8c90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8ca0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 to request that
8cb0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e the VFS.** exten
8cc0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 ds and truncates
8cd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
8ce0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 le in chunks of
8cf0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 a size specified
8d00: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e .** by the user.
8d10: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 The fourth argu
8d20: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
8d30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
8d40: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e should .** poin
8d50: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 t to an integer
8d60: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 (type int) conta
8d70: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 ining the new ch
8d80: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a unk-size to use.
8d90: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e ** for the nomin
8da0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 ated database. A
8db0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 llocating databa
8dc0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e se file space in
8dd0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 large.** chunks
8de0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 (say 1MB at a t
8df0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 ime), may reduce
8e00: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 file-system fra
8e10: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a gmentation and.*
8e20: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 * improve perfor
8e30: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 mance on some sy
8e40: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 stems..**.** <li
8e50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
8e60: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a FILE_POINTER]].*
8e70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
8e80: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
8e90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
8ea0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 to obtain a poi
8eb0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
8ec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
8ed0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 ject associated
8ee0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
8ef0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f r database.** co
8f00: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 nnection. See t
8f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
8f20: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 _control()] docu
8f30: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
8f40: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
8f50: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c rmation..**.** <
8f60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
8f70: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d L_SYNC_OMITTED]]
8f80: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
8f90: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
8fa0: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 TTED] opcode is
8fb0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e generated intern
8fc0: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 ally by.** SQLit
8fd0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c e and sent to al
8fe0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 l VFSes in place
8ff0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 of a call to th
9000: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a e xSync method.*
9010: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 * when the datab
9020: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 ase connection h
9030: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 as [PRAGMA synch
9040: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f ronous] set to O
9050: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 FF.)^.** Some sp
9060: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
9070: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c need this signal
9080: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 in order to ope
9090: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a rate correctly.*
90a0: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 * when [PRAGMA s
90b0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 ynchronous | PRA
90c0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d GMA synchronous=
90d0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 OFF] is set, but
90e0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 most .** VFSes
90f0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 do not need this
9100: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 signal and shou
9110: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
9120: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a re this opcode..
9130: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** Applications
9140: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
9150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9160: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
9170: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 is.** opcode as
9180: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 doing so may dis
9190: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 rupt the operati
91a0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 on of the specia
91b0: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 lized VFSes.** t
91c0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 hat do require i
91d0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b t. .**.** <li>[
91e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 [SQLITE_FCNTL_WI
91f0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a N32_AV_RETRY]].*
9200: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
9210: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
9220: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TRY] opcode is u
9230: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 sed to configure
9240: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 automatic.** re
9250: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 try counts and i
9260: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 ntervals for cer
9270: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 tain disk I/O op
9280: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 erations for the
9290: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 .** windows [VFS
92a0: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 ] in order to pr
92b0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 ovide robustness
92c0: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 in the presence
92d0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 of.** anti-viru
92e0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 s programs. By
92f0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e default, the win
9300: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 dows VFS will re
9310: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a try file read,.*
9320: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e * file write, an
9330: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 d file delete op
9340: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 erations up to 1
9350: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 0 times, with a
9360: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d delay.** of 25 m
9370: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f illiseconds befo
9380: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 re the first ret
9390: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 ry and with the
93a0: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 delay increasing
93b0: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 .** by an additi
93c0: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 onal 25 millisec
93d0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 onds with each s
93e0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e ubsequent retry.
93f0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
9400: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 allows these tw
9410: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 o values (10 ret
9420: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c ries and 25 mill
9430: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 iseconds of dela
9440: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 y).** to be adju
9450: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 sted. The value
9460: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f s are changed fo
9470: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 r all database c
9480: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 onnections.** wi
9490: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 thin the same pr
94a0: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 ocess. The argu
94b0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
94c0: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 r to an array of
94d0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 two.** integers
94e0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 where the first
94f0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e integer i the n
9500: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 ew retry count a
9510: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a nd the second.**
9520: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 integer is the
9530: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 delay. If eithe
9540: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 r integer is neg
9550: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 ative, then the
9560: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f setting.** is no
9570: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e t changed but in
9580: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 stead the prior
9590: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 value of that se
95a0: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e tting is written
95b0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 .** into the arr
95c0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 ay entry, allowi
95d0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 ng the current r
95e0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f etry settings to
95f0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 be.** interroga
9600: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d ted. The zDbNam
9610: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 e parameter is i
9620: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c gnored..**.** <l
9630: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9640: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a _PERSIST_WAL]].*
9650: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
9660: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c CNTL_PERSIST_WAL
9670: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
9680: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
9690: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
96a0: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 nt [WAL | Write
96b0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 Ahead Log] setti
96c0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ng. By default,
96d0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a the auxiliary.*
96e0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f * write ahead lo
96f0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d g and shared mem
9700: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 ory files used f
9710: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 or transaction c
9720: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 ontrol.** are au
9730: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 tomatically dele
9740: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 ted when the lat
9750: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 est connection t
9760: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
9770: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 * closes. Setti
9780: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 ng persistent WA
9790: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 L mode causes th
97a0: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 ose files to per
97b0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c sist after.** cl
97c0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 ose. Persisting
97d0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 the files is us
97e0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 eful when other
97f0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 processes that d
9800: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 o not.** have wr
9810: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f ite permission o
9820: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 n the directory
9830: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 containing the d
9840: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e atabase file wan
9850: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 t.** to read the
9860: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
9870: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 as the WAL and s
9880: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
9890: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a es must exist.**
98a0: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 in order for th
98b0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 e database to be
98c0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
98d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
98e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
98f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
9900: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
9910: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
9920: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
9930: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
9940: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
9950: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 le persistent WA
9960: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 L mode or 1 to e
9970: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 nable persistent
9980: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 .** WAL mode. I
9990: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
99a0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
99b0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
99c0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
99d0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 WAL persistence
99e0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
99f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
9a00: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 L_POWERSAFE_OVER
9a10: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
9a20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f [SQLITE_FCNTL_PO
9a30: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
9a40: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
9a50: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 d to set or quer
9a60: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 y the.** persist
9a70: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f ent "powersafe-o
9a80: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 verwrite" or "PS
9a90: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 OW" setting. Th
9aa0: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a e PSOW setting.*
9ab0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 * determines the
9ac0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 [SQLITE_IOCAP_P
9ad0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
9ae0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a TE] bit of the.*
9af0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 * xDeviceCharact
9b00: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 eristics methods
9b10: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 . The fourth par
9b20: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 ameter to.** [sq
9b30: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
9b40: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f ol()] for this o
9b50: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 pcode should be
9b60: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
9b70: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 integer..** That
9b80: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f integer is 0 to
9b90: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 disable zero-da
9ba0: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 mage mode or 1 t
9bb0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 o enable zero-da
9bc0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 mage.** mode. I
9bd0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 f the integer is
9be0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 -1, then it is
9bf0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
9c00: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 the current.**
9c10: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
9c20: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 setting..**.**
9c30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9c40: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a TL_OVERWRITE]].*
9c50: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
9c60: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 CNTL_OVERWRITE]
9c70: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 opcode is invoke
9c80: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 d by SQLite afte
9c90: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 r opening.** a w
9ca0: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e rite transaction
9cb0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
9cc0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 t, unless it is
9cd0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 rolled back for
9ce0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 some.** reason,
9cf0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 the entire datab
9d00: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 ase file will be
9d10: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 overwritten by
9d20: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 the current .**
9d30: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 transaction. Thi
9d40: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 s is used by VAC
9d50: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a UUM operations..
9d60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9d70: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
9d80: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
9d90: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 TE_FCNTL_VFSNAME
9da0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 ] opcode can be
9db0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 used to obtain t
9dc0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 he names of.** a
9dd0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 ll [VFSes] in th
9de0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 e VFS stack. Th
9df0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 e names are of a
9e00: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 ll VFS shims and
9e10: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f the.** final bo
9e20: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 ttom-level VFS a
9e30: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 re written into
9e40: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
9e50: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
9e60: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
9e70: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 the result is st
9e80: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 ored in the char
9e90: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 * variable.** th
9ea0: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 at the fourth pa
9eb0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 rameter of [sqli
9ec0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9ed0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a ()] points to..*
9ee0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 * The caller is
9ef0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 responsible for
9f00: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f freeing the memo
9f10: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 ry when done. A
9f20: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 s with.** all fi
9f30: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f le-control actio
9f40: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 ns, there is no
9f50: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 guarantee that t
9f60: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c his will actuall
9f70: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 y.** do anything
9f80: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c . Callers shoul
9f90: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 d initialize the
9fa0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 char* variable
9fb0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 to a NULL.** poi
9fc0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 nter in case thi
9fd0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
9fe0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 s not implemente
9ff0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f d. This file-co
a000: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 ntrol.** is inte
a010: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 nded for diagnos
a020: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a tic use only..**
a030: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a040: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a _FCNTL_PRAGMA]].
a050: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b ** ^Whenever a [
a060: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
a070: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 t is parsed, an
a080: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
a090: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 AGMA] .** file c
a0a0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 ontrol is sent t
a0b0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 o the open [sqli
a0c0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
a0d0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
a0e0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 * to the databas
a0f0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 e file to which
a100: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 the pragma state
a110: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 ment refers. ^Th
a120: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
a130: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
a140: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
a150: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 control is an ar
a160: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 ray of.** pointe
a170: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 rs to strings (c
a180: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 har**) in which
a190: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 the second eleme
a1a0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a nt of the array.
a1b0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
a1c0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 f the pragma and
a1d0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 the third eleme
a1e0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 nt is the argume
a1f0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 nt to the.** pra
a200: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 gma or NULL if t
a210: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f he pragma has no
a220: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 argument. ^The
a230: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a handler for an.
a240: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
a250: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a260: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e ntrol can option
a270: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 ally make the fi
a280: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f rst element.** o
a290: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 f the char** arg
a2a0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 ument point to a
a2b0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
a2c0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
a2d0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 printf()].** or
a2e0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 the equivalent a
a2f0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 nd that string w
a300: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 ill become the r
a310: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 esult of the pra
a320: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 gma or.** the er
a330: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 ror message if t
a340: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e he pragma fails.
a350: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a370: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 ] file control r
a380: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e eturns [SQLITE_N
a390: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e OTFOUND], then n
a3a0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d ormal .** [PRAGM
a3b0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f A] processing co
a3c0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 ntinues. ^If th
a3d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a3e0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
a3f0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
a400: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 [SQLITE_OK], the
a410: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 n the parser ass
a420: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
a430: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 VFS has handled
a440: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 the PRAGMA itse
a450: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 lf and the parse
a460: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f r generates a no
a470: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 -op.** prepared
a480: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 statement. ^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 20 66 69 6c 65 20 63 L_PRAGMA] file c
a4b0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a ontrol returns.*
a4c0: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 * any result cod
a4d0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 e other than [SQ
a4e0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c LITE_OK] or [SQL
a4f0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 ITE_NOTFOUND], t
a500: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 hat means.** tha
a510: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e t the VFS encoun
a520: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 tered an error w
a530: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 hile handling th
a540: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 e [PRAGMA] and t
a550: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f he.** compilatio
a560: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 n of the PRAGMA
a570: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 fails with an er
a580: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 ror. ^The [SQLI
a590: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
a5a0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
a5b0: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 occurs at the b
a5c0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 eginning of prag
a5d0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 ma statement ana
a5e0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 lysis and so.**
a5f0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 it is able to ov
a600: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 erride built-in
a610: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 [PRAGMA] stateme
a620: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nts..**.** <li>[
a630: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 [SQLITE_FCNTL_BU
a640: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e SYHANDLER]].** ^
a650: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a660: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a L_BUSYHANDLER].*
a670: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d * file-control m
a680: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 ay be invoked by
a690: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 SQLite on the d
a6a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e atabase file han
a6b0: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 dle.** shortly a
a6c0: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 fter it is opene
a6d0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 d in order to pr
a6e0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 ovide a custom V
a6f0: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a FS with access.*
a700: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 * to the connect
a710: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 ions busy-handle
a720: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 r callback. The
a730: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 argument is of t
a740: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a ype (void **).**
a750: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 - an array of t
a760: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 wo (void *) valu
a770: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 es. The first (v
a780: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 oid *) actually
a790: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 points.** to a f
a7a0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
a7b0: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 (int (*)(void *)
a7c0: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 ). In order to i
a7d0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 nvoke the connec
a7e0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 tions.** busy-ha
a7f0: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 ndler, this func
a800: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 tion should be i
a810: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 nvoked with the
a820: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 second (void *)
a830: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 in.** the array
a840: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 as the only argu
a850: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 ment. If it retu
a860: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
a870: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e en the operation
a880: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
a890: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 tried. If it ret
a8a0: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 urns zero, the c
a8b0: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 ustom VFS should
a8c0: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 abandon the.**
a8d0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f current operatio
a8e0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 n..**.** <li>[[S
a8f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
a900: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 FILENAME]].** ^A
a910: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 pplication can i
a920: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 nvoke the [SQLIT
a930: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 E_FCNTL_TEMPFILE
a940: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 NAME] file-contr
a950: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 ol.** to have SQ
a960: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a Lite generate a.
a970: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
a980: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 ename using the
a990: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 same algorithm t
a9a0: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 hat is followed
a9b0: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 to generate.** t
a9c0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d emporary filenam
a9d0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c es for TEMP tabl
a9e0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 es and other int
a9f0: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 ernal uses. The
aa00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f .** argument sho
aa10: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 uld be a char**
aa20: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 which will be fi
aa30: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 lled with the fi
aa40: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 lename.** writte
aa50: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
aa60: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
aa70: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
aa80: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 The caller shou
aa90: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 ld.** invoke [sq
aaa0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e lite3_free()] on
aab0: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 the result to a
aac0: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 void a memory le
aad0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ak..**.** <li>[[
aae0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
aaf0: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 P_SIZE]].** The
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d [SQLITE_FCNTL_MM
ab10: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f AP_SIZE] file co
ab20: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f ntrol is used to
ab30: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 query or set th
ab40: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d e.** maximum num
ab50: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 ber of bytes tha
ab60: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 t will be used f
ab70: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 or memory-mapped
ab80: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 I/O..** The arg
ab90: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
aba0: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 er to a value of
abb0: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e type sqlite3_in
abc0: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 t64 that.** is a
abd0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d n advisory maxim
abe0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 um number of byt
abf0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 es in the file t
ac00: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 o memory map. T
ac10: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 he.** pointer is
ac20: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 overwritten wit
ac30: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e h the old value.
ac40: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e The limit is n
ac50: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a ot changed if.**
ac60: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 the value origi
ac70: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f nally pointed to
ac80: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e is negative, an
ac90: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 d so the current
aca0: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 limit .** can b
acb0: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 e queried by pas
acc0: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 sing in a pointe
acd0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 r to a negative
ace0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a number. This.**
acf0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
ad00: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 used internally
ad10: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 to implement [P
ad20: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
ad30: 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f ..**.** </ul>.*/
ad40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ad50: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 FCNTL_LOCKSTATE
ad60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
ad70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
ad80: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
ad90: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
ada0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 define SQLITE_SE
adb0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
adc0: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
add0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 efine SQLITE_LAS
ade0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 T_ERRNO
adf0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
ae00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ae10: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 L_SIZE_HINT
ae20: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
ae30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ae40: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 _CHUNK_SIZE
ae50: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6.#defi
ae60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
ae70: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 FILE_POINTER
ae80: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 7.#defin
ae90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
aea0: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 YNC_OMITTED
aeb0: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
aec0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 SQLITE_FCNTL_WI
aed0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 N32_AV_RETRY
aee0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
aef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
af00: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 SIST_WAL
af10: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
af20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
af30: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 WRITE
af40: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 11.#define SQ
af50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
af60: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ME
af70: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 12.#define SQL
af80: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
af90: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
afa0: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 13.#define SQLI
afb0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 TE_FCNTL_PRAGMA
afc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
afd0: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 14.#define SQLIT
afe0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
aff0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 LER 1
b000: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
b010: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
b020: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 AME 16
b030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b040: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 FCNTL_MMAP_SIZE
b050: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 18.
b060: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
b070: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
b080: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
b090: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
b0a0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
b0b0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
b0c0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
b0d0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
b0e0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
b0f0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
b100: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
b110: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
b120: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
b130: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
b140: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
b150: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
b160: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
b170: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
b180: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
b190: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
b1a0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
b1b0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
b1c0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
b1d0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
b1e0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
b1f0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
b200: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
b210: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
b220: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
b230: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
b240: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
b250: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
b260: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
b270: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
b280: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
b290: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
b2a0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
b2b0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
b2c0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
b2d0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
b2e0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
b2f0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
b300: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
b310: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
b320: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
b330: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
b340: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
b350: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
b360: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
b370: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
b380: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
b390: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
b3a0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
b3b0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
b3c0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
b3d0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
b3e0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
b3f0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
b400: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
b410: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
b420: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
b430: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
b440: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
b450: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
b460: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
b470: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
b480: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
b490: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
b4a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
b4b0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
b4c0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
b4d0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
b4e0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
b4f0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
b500: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
b510: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
b520: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
b530: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
b540: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
b550: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
b560: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
b570: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
b580: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
b590: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
b5a0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
b5b0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
b5c0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
b5d0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
b5e0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
b5f0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
b600: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
b610: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
b620: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
b630: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
b640: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
b650: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
b660: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
b670: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
b680: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
b690: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
b6a0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
b6b0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
b6c0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
b6d0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
b6e0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
b6f0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
b700: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
b710: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
b720: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
b730: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
b740: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
b750: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
b760: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
b770: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
b780: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
b790: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
b7a0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
b7b0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
b7c0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
b7d0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
b7e0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
b7f0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
b800: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
b810: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
b820: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
b830: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
b840: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
b850: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
b860: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
b870: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
b880: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
b890: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
b8a0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
b8b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
b8c0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
b8d0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
b8e0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
b8f0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
b900: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
b910: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
b920: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
b930: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
b940: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
b950: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
b960: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
b970: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
b980: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
b990: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
b9a0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
b9b0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
b9c0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
b9d0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
b9e0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
b9f0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
ba00: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
ba10: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
ba20: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
ba30: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
ba40: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
ba50: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
ba60: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
ba70: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
ba80: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
ba90: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
baa0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
bab0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
bac0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
bad0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
bae0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
baf0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
bb00: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
bb10: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
bb20: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
bb30: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
bb40: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
bb50: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
bb60: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
bb70: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
bb80: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
bb90: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
bba0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
bbb0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
bbc0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
bbd0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
bbe0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
bbf0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
bc00: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
bc10: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
bc20: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
bc30: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
bc40: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
bc50: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
bc60: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
bc70: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
bc80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
bc90: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
bca0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
bcb0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
bcc0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
bcd0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
bce0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
bcf0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
bd00: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
bd10: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
bd20: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
bd30: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
bd40: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
bd50: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
bd60: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
bd70: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
bd80: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
bd90: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
bda0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
bdb0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
bdc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
bdd0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
bde0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
bdf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
be00: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
be10: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
be20: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
be30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
be40: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
be50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
be60: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
be70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
be80: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
be90: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
bea0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
beb0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
bec0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
bed0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
bee0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
bef0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
bf00: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
bf10: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
bf20: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
bf30: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
bf40: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
bf50: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
bf60: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
bf70: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
bf80: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
bf90: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
bfa0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
bfb0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
bfc0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
bfd0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
bfe0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
bff0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
c000: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
c010: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
c020: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
c030: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
c040: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
c050: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
c060: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
c070: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
c080: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
c090: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
c0a0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
c0b0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
c0c0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
c0d0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
c0e0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
c0f0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
c100: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
c110: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
c120: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
c130: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
c140: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
c150: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
c160: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
c170: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
c180: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
c190: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
c1a0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
c1b0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
c1c0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
c1d0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
c1e0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
c1f0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
c200: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
c210: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
c220: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
c230: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
c240: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
c250: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
c260: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
c270: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
c280: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
c290: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
c2a0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
c2b0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
c2c0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
c2d0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
c2e0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
c2f0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
c300: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
c310: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
c320: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
c330: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
c340: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
c350: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
c360: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
c370: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
c380: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
c390: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
c3a0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
c3b0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
c3c0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
c3d0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
c3e0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
c3f0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
c400: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
c410: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
c420: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
c430: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
c440: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
c450: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
c460: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
c470: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
c480: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
c490: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
c4a0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
c4b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
c4c0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
c4d0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
c4e0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
c4f0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
c500: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
c510: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
c520: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
c530: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
c540: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
c550: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
c560: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
c570: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
c580: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
c590: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
c5a0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
c5b0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
c5c0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
c5d0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
c5e0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
c5f0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
c600: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
c610: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
c620: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
c630: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
c640: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
c650: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
c660: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
c670: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
c680: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
c690: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
c6a0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
c6b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
c6c0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
c6d0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
c6e0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
c6f0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
c700: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
c710: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
c720: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
c730: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
c740: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
c750: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
c760: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
c770: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
c780: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
c790: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
c7a0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
c7b0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
c7c0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
c7d0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
c7e0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
c7f0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
c800: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
c810: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
c820: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
c830: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
c840: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
c850: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
c860: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
c870: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
c880: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
c890: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
c8a0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
c8b0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
c8c0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
c8d0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
c8e0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
c8f0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
c900: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
c910: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
c920: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
c930: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
c940: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
c950: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
c960: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
c970: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
c980: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
c990: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
c9a0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
c9b0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
c9c0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
c9d0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
c9e0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
c9f0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
ca00: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
ca10: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
ca20: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
ca30: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
ca40: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
ca50: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
ca60: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
ca70: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
ca80: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
ca90: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
caa0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
cab0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
cac0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
cad0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
cae0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
caf0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
cb00: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
cb10: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
cb20: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
cb30: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
cb40: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
cb50: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
cb60: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
cb70: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
cb80: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
cb90: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
cba0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
cbb0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
cbc0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
cbd0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
cbe0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
cbf0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
cc00: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
cc10: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
cc20: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
cc30: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
cc40: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
cc50: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
cc60: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
cc70: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
cc80: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
cc90: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
cca0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
ccb0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
ccc0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
ccd0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
cce0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
ccf0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
cd00: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
cd10: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
cd20: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
cd30: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
cd40: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
cd50: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
cd60: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
cd70: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
cd80: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
cd90: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
cda0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
cdb0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
cdc0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
cdd0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
cde0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
cdf0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
ce00: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
ce10: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
ce20: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
ce30: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
ce40: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
ce50: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
ce60: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
ce70: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
ce80: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
ce90: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
cea0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
ceb0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
cec0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
ced0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
cee0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
cef0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
cf00: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
cf10: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
cf20: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
cf30: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
cf40: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
cf50: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
cf60: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
cf70: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
cf80: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
cf90: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
cfa0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
cfb0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
cfc0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
cfd0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
cfe0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
cff0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
d000: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
d010: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
d020: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
d030: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
d040: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
d050: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
d060: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
d070: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
d080: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
d090: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
d0a0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
d0b0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
d0c0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
d0d0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
d0e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
d0f0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
d100: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
d110: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
d120: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
d130: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
d140: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
d150: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
d160: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
d170: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
d180: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
d190: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
d1a0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
d1b0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
d1c0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
d1d0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
d1e0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
d1f0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
d200: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
d210: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
d220: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
d230: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
d240: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
d250: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
d260: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
d270: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
d280: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
d290: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
d2a0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
d2b0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
d2c0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
d2d0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
d2e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
d2f0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
d300: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
d310: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
d320: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
d330: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
d340: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
d350: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
d360: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
d370: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
d380: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
d390: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
d3a0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
d3b0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
d3c0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
d3d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
d3e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
d3f0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
d400: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
d410: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
d420: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
d430: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
d440: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
d450: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
d460: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
d470: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
d480: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
d490: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
d4a0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
d4b0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
d4c0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
d4d0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
d4e0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
d4f0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
d500: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
d510: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
d520: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
d530: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
d540: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
d550: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
d560: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
d570: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
d580: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
d590: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
d5a0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
d5b0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
d5c0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
d5d0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
d5e0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
d5f0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
d600: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
d610: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
d620: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
d630: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
d640: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
d650: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
d660: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
d670: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
d680: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
d690: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
d6a0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
d6b0: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
d6c0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
d6d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
d6e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
d6f0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
d700: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
d710: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
d720: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
d730: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
d740: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
d750: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
d760: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
d770: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
d780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
d790: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
d7a0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
d7b0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
d7c0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
d7d0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
d7e0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
d7f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
d800: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 pended in figure
d810: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
d820: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
d830: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
d840: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
d850: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
d860: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
d870: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
d880: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
d890: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
d8a0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
d8b0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
d8c0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
d8d0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
d8e0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
d8f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
d900: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
d910: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
d920: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
d930: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
d940: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
d950: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
d960: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
d970: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
d980: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
d990: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
d9a0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
d9b0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
d9c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
d9d0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
d9e0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
d9f0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
da00: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
da10: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
da20: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
da30: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
da40: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
da50: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
da60: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
da70: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
da80: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
da90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
daa0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
dab0: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
dac0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
dad0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
dae0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
daf0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
db00: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
db10: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
db20: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
db30: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
db40: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
db50: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
db60: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
db70: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
db80: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
db90: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
dba0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
dbb0: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
dbc0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
dbd0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
dbe0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
dbf0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
dc00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
dc10: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
dc20: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
dc30: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
dc40: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
dc50: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
dc60: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
dc70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
dc80: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
dc90: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
dca0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
dcb0: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
dcc0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
dcd0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
dce0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
dcf0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
dd00: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
dd10: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
dd20: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
dd30: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
dd40: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
dd50: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
dd60: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
dd70: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
dd80: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
dd90: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
dda0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
ddb0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
ddc0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
ddd0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
dde0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
ddf0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
de00: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
de10: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
de20: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
de30: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
de40: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
de50: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
de60: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
de70: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
de80: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
de90: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
dea0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
deb0: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
dec0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 was given no th
ded0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
dee0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
def0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
df00: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
df10: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
df20: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
df30: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
df40: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
df50: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
df60: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
df70: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
df80: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
df90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
dfa0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
dfb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
dfc0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
dfd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dfe0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
dff0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
e000: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
e010: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
e020: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
e030: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
e040: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
e050: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
e060: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
e070: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
e080: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
e090: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
e0a0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
e0b0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
e0c0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
e0d0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
e0e0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
e0f0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
e100: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
e110: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
e120: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
e130: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
e140: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
e150: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
e160: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
e170: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
e180: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
e190: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
e1a0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
e1b0: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
e1c0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
e1d0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
e1e0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
e1f0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
e200: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
e210: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
e220: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
e230: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
e240: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
e250: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
e260: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
e270: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
e280: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
e290: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
e2a0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
e2b0: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
e2c0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
e2d0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
e2e0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
e2f0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
e300: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
e310: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
e320: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
e330: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
e340: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e350: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
e360: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
e370: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
e380: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
e390: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
e3a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
e3b0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
e3c0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
e3d0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
e3e0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
e3f0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
e400: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
e410: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e420: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
e430: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
e440: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
e450: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
e460: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
e470: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
e480: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
e490: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
e4a0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
e4b0: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
e4c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
e4d0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
e4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e4f0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
e500: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
e510: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
e520: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
e530: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
e540: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
e550: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
e560: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
e570: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
e580: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
e590: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
e5a0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
e5b0: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
e5c0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
e5d0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
e5e0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
e5f0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
e600: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
e610: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
e620: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
e630: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
e640: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
e650: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
e660: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
e670: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
e680: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
e690: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
e6a0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
e6b0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
e6c0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
e6d0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
e6e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e6f0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
e700: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
e710: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
e720: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
e730: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
e740: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
e750: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
e760: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e770: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
e780: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
e790: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
e7a0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
e7b0: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
e7c0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
e7d0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
e7e0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
e7f0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
e800: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
e810: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
e820: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
e830: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
e840: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
e850: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
e860: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
e870: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
e880: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
e890: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
e8a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
e8b0: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
e8c0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
e8d0: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
e8e0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
e8f0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
e900: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
e910: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
e920: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
e930: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
e940: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
e950: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e960: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
e970: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
e980: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
e990: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
e9a0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
e9b0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
e9c0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
e9d0: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
e9e0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
e9f0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
ea00: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
ea10: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
ea20: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
ea30: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
ea40: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
ea50: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
ea60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
ea70: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
ea80: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
ea90: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
eaa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
eab0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
eac0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
ead0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
eae0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
eaf0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
eb00: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
eb10: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
eb20: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
eb30: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
eb40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
eb50: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
eb60: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
eb70: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
eb80: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
eb90: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
eba0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
ebb0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
ebc0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
ebd0: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
ebe0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
ebf0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
ec00: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
ec10: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
ec20: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
ec30: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
ec40: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
ec50: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
ec60: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
ec70: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
ec80: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
ec90: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
eca0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
ecb0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
ecc0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
ecd0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
ece0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
ecf0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
ed00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
ed10: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
ed20: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
ed30: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
ed40: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
ed50: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
ed60: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
ed70: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
ed80: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
ed90: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
eda0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
edb0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
edc0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
edd0: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
ede0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
edf0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
ee00: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
ee10: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
ee20: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
ee30: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
ee40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
ee50: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
ee60: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
ee70: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
ee80: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
ee90: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
eea0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
eeb0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
eec0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
eed0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
eee0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
eef0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
ef00: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
ef10: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
ef20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
ef30: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
ef40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
ef50: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
ef60: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
ef70: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
ef80: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
ef90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
efa0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
efb0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
efc0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
efd0: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
efe0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
eff0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
f000: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
f010: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
f020: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
f030: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
f040: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
f050: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
f060: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
f070: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
f080: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
f090: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
f0a0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
f0b0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
f0c0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
f0d0: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
f0e0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
f0f0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
f100: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
f110: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
f120: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
f130: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
f140: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
f150: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
f160: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 */.int sqlite3_i
f170: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
f180: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 .int sqlite3_shu
f190: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 tdown(void);.int
f1a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
f1b0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
f1c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
f1d0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
f1e0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
f1f0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
f200: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 y.**.** The sqli
f210: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
f220: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
f230: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f o make global co
f240: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
f250: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 hanges to SQLite
f260: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e in order to tun
f270: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 e SQLite to the
f280: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
f290: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
f2a0: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 tion. The defau
f2b0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
f2c0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
f2d0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c for most.** appl
f2e0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 ications and so
f2f0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
f300: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 usually not nece
f310: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a ssary. It is.**
f320: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 provided to sup
f330: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 port rare applic
f340: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 ations with unus
f350: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ual needs..**.**
f360: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
f370: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
f380: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
f390: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 e. The applicat
f3a0: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 ion.** must insu
f3b0: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 re that no other
f3c0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
f3d0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 es are invoked b
f3e0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 y other.** threa
f3f0: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 ds while sqlite3
f400: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e _config() is run
f410: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f ning. Furthermo
f420: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 re, sqlite3_conf
f430: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ig().** may only
f440: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f be invoked prio
f450: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 r to library ini
f460: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e tialization usin
f470: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e g.** [sqlite3_in
f480: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 itialize()] or a
f490: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 fter shutdown by
f4a0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
f4b0: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 wn()]..** ^If sq
f4c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
f4d0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b s called after [
f4e0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
f4f0: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 ze()] and before
f500: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
f510: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 tdown()] then it
f520: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c will return SQL
f530: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e ITE_MISUSE..** N
f540: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 ote, however, th
f550: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 at ^sqlite3_conf
f560: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
f570: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
f580: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
f590: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
f5a0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
f5b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
f5c0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
f5d0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
f5e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
f5f0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
f600: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
f610: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
f620: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
f630: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
f640: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
f650: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
f660: 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
f670: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
f680: 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 on the [configur
f690: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
f6a0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
f6b0: 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 gument..**.** ^W
f6c0: 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
f6d0: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
f6e0: 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
f6f0: 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
f700: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 ITE_OK]..** ^If
f710: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e the option is un
f720: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 known or SQLite
f730: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 is unable to set
f740: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 the option.** t
f750: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
f760: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a returns a non-z
f770: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
f780: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
f790: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
f7a0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
f7b0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
f7c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
f7d0: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ns.**.** The sql
f7e0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
f7f0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
f800: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
f810: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
f820: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
f830: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
f840: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
f850: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
f860: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
f870: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
f880: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
f890: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
f8a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
f8b0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
f8c0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
f8d0: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
f8e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
f8f0: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
f900: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
f910: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
f920: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
f930: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
f940: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
f950: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
f960: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
f970: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
f980: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
f990: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
f9a0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
f9b0: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
f9c0: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
f9d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
f9e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
f9f0: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
fa00: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
fa10: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
fa20: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
fa30: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
fa40: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
fa50: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 successful..*/.i
fa60: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f nt sqlite3_db_co
fa70: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
fa80: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
fa90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
faa0: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
fab0: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 Routines.**.** A
fac0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
fad0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
fae0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
faf0: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
fb00: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
fb10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
fb20: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
fb30: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
fb40: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
fb50: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
fb60: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
fb70: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
fb80: 20 61 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 69 73 20 74 this object is t
fba0: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
fbb0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
fbc0: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
fbd0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
fbe0: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
fbf0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 _CONFIG_MALLOC]
fc00: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
fc10: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a G_GETMALLOC]. .
fc20: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 ** By creating a
fc30: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
fc40: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
fc50: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
fc60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
fc70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
fc80: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e ALLOC]).** durin
fc90: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
fca0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
fcb0: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
fcc0: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
fcd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
fce0: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 subsystem for SQ
fcf0: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
fd00: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 all of its.** dy
fd10: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
fd20: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
fd30: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
fd40: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 with several [b
fd50: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
fd60: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 llocators].** th
fd70: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 at are perfectly
fd80: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
fd90: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
fda0: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
fdb0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
fdc0: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
fdd0: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
fde0: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
fdf0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
fe00: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
fe10: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
fe20: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
fe30: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
fe40: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
fe50: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
fe60: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
fe70: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
fe80: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
fe90: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
fea0: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
feb0: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
fec0: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
fed0: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
fee0: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
fef0: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
ff00: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
ff10: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
ff20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
ff30: 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e oc, xRealloc, an
ff40: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 d xFree methods
ff50: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 must work like t
ff60: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 he.** malloc(),
ff70: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 realloc() and fr
ff80: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 ee() functions f
ff90: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 rom the standard
ffa0: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e C library..** ^
ffb0: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
ffc0: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
ffd0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
ffe0: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 xRealloc is alw
fff0: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 ays a value retu
10000 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 rned by a prior
10010 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 call to xRoundup
10020 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 ..**.** xSize sh
10030 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
10040 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
10050 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
10060 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 ation.** previou
10070 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f sly obtained fro
10080 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 m xMalloc or xRe
10090 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f alloc. The allo
100a0 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 cated size.** is
100b0 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 always at least
100c0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 as big as the r
100d0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 equested size bu
100e0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e t may be larger.
100f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e .**.** The xRoun
10100 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 dup method retur
10110 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 ns what would be
10120 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
10130 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f ize of.** a memo
10140 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 ry allocation gi
10150 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ven a particular
10160 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e requested size.
10170 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a Most memory.**
10180 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
10190 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f d up memory allo
101a0 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 cations at least
101b0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c to the next mul
101c0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 tiple.** of 8.
101d0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 Some allocators
101e0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 round up to a la
101f0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 rger multiple or
10200 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 to a power of 2
10210 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 ..** Every memor
10220 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
10230 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 uest coming in t
10240 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f hrough [sqlite3_
10250 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 malloc()].** or
10260 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
10270 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 ()] first calls
10280 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 xRoundup. If xR
10290 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 oundup returns 0
102a0 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 , .** that cause
102b0 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 s the correspond
102c0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ing memory alloc
102d0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a ation to fail..*
102e0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
102f0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
10300 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
10310 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 ocator. (For ex
10320 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 ample,.** it mig
10330 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 ht allocate any
10340 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 require mutexes
10350 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e or initialize in
10360 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 ternal data.** s
10370 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 tructures. The
10380 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
10390 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 is invoked (ind
103a0 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b irectly) by.** [
103b0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
103c0 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 ()] and should d
103d0 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 eallocate any re
103e0 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 sources acquired
103f0 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 .** by xInit. T
10400 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e he pAppData poin
10410 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 ter is used as t
10420 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
10430 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e r to.** xInit an
10440 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a d xShutdown..**.
10450 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 ** SQLite holds
10460 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 the [SQLITE_MUTE
10470 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d X_STATIC_MASTER]
10480 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 mutex when it i
10490 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 nvokes.** the xI
104a0 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 nit method, so t
104b0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
104c0 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 need not be thre
104d0 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 adsafe. The.**
104e0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
104f0 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 is only called
10500 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 from [sqlite3_sh
10510 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 utdown()] so it
10520 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 does.** not need
10530 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 to be threadsaf
10540 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 e either. For a
10550 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 ll other methods
10560 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 , SQLite.** hold
10570 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
10580 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 TEX_STATIC_MEM]
10590 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 mutex as long as
105a0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
105b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
105c0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 ] configuration
105d0 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 option is turned
105e0 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 on (which.** it
105f0 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 is by default)
10600 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f and so the metho
10610 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ds are automatic
10620 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e ally serialized.
10630 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 .** However, if
10640 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
10650 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 EMSTATUS] is dis
10660 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 abled, then the
10670 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 other.** methods
10680 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
10690 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 afe or else make
106a0 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e their own arran
106b0 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 gements for.** s
106c0 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a erialization..**
106d0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
106e0 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e never invoke xIn
106f0 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f it() more than o
10700 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 nce without an i
10710 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 ntervening.** ca
10720 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 ll to xShutdown(
10730 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 )..*/.typedef st
10740 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
10750 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
10760 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 _mem_methods;.st
10770 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
10780 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 _methods {. voi
10790 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e d *(*xMalloc)(in
107a0 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d t); /* M
107b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
107c0 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
107d0 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 oid (*xFree)(voi
107e0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a d*); /*
107f0 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c Free a prior al
10800 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f location */. vo
10810 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 id *(*xRealloc)(
10820 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 void*,int); /*
10830 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 Resize an alloca
10840 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a tion */. int (*
10850 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 xSize)(void*);
10860 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 /* Retu
10870 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 rn the size of a
10880 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a n allocation */.
10890 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 int (*xRoundup
108a0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
108b0 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 /* Round up req
108c0 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c uest size to all
108d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a ocation size */.
108e0 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 int (*xInit)(v
108f0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
10900 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 /* Initialize t
10910 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
10920 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a tor */. void (*
10930 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a xShutdown)(void*
10940 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 ); /* Deini
10950 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
10960 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
10970 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 void *pAppData
10980 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
10990 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 /* Argument to
109a0 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 xInit() and xShu
109b0 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f tdown() */.};../
109c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
109d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
109e0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
109f0 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e : {configuration
10a00 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 option}.**.** T
10a10 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
10a20 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 re the available
10a30 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 integer configu
10a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 ration options t
10a50 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 hat.** can be pa
10a60 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
10a70 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
10a80 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
10a90 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
10aa0 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
10ab0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
10ac0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
10ad0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
10ae0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
10af0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
10b00 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
10b10 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
10b20 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
10b30 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
10b40 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
10b50 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
10b60 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
10b70 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
10b80 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
10b90 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
10ba0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
10bb0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
10bc0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
10bd0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
10be0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
10bf0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
10c00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
10c10 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
10c20 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
10c30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
10c40 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 LETHREAD]] <dt>S
10c50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
10c60 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a GLETHREAD</dt>.*
10c70 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
10c80 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
10c90 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
10ca0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
10cb0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
10cc0 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c g mode] to Singl
10cd0 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 e-thread. In ot
10ce0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 her words, it di
10cf0 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 sables.** all mu
10d00 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 texing and puts
10d10 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f SQLite into a mo
10d20 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 de where it can
10d30 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 only be used.**
10d40 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 by a single thre
10d50 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 ad. ^If SQLite
10d60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
10d70 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
10d80 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
10d90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
10da0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
10db0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
10dc0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
10dd0 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 e to change the
10de0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
10df0 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c from its defaul
10e00 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 t.** value of Si
10e10 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 ngle-thread and
10e20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 so [sqlite3_conf
10e30 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
10e40 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 n .** [SQLITE_ER
10e50 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
10e60 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
10e70 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
10e80 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 AD.** configurat
10e90 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
10ea0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
10eb0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
10ec0 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AD]] <dt>SQLITE_
10ed0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
10ee0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
10ef0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
10f00 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
10f10 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
10f20 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
10f30 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
10f40 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 to Multi-thread
10f50 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
10f60 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a s, it disables.*
10f70 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 * mutexing on [d
10f80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10f90 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
10fa0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
10fb0 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ects..** The app
10fc0 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 lication is resp
10fd0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 onsible for seri
10fe0 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 alizing access t
10ff0 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 o.** [database c
11000 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
11010 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
11020 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 ents]. But othe
11030 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 r mutexes.** are
11040 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 enabled so that
11050 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
11060 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 safe to use in a
11070 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a multi-threaded.
11080 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 ** environment a
11090 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f s long as no two
110a0 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 threads attempt
110b0 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
110c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
110d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 nnection] at the
110e0 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 same time. ^If
110f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
11100 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
11110 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
11120 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
11130 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
11140 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
11150 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
11160 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
11170 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 the Multi-thread
11180 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
11190 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
111a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
111b0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
111c0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
111d0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c with the.** SQL
111e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
111f0 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 THREAD configura
11200 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
11210 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
11220 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
11230 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f ED]] <dt>SQLITE_
11240 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
11250 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
11260 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
11270 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
11280 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
11290 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
112a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
112b0 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 to Serialized. I
112c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
112d0 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c his option enabl
112e0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 es.** all mutexe
112f0 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 s including the
11300 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 recursive.** mut
11310 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 exes on [databas
11320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
11330 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
11340 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
11350 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 ** In this mode
11360 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 (which is the de
11370 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 fault when SQLit
11380 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
11390 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 th.** [SQLITE_TH
113a0 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 READSAFE=1]) the
113b0 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
113c0 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 will itself seri
113d0 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 alize access.**
113e0 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e to [database con
113f0 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 nections] and [p
11400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11410 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a ts] so that the.
11420 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 ** application i
11430 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 s free to use th
11440 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
11450 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 connection] or
11460 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 the.** same [pre
11470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
11480 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 in different th
11490 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
114a0 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 e time..** ^If S
114b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
114c0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
114d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
114e0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
114f0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
11500 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
11510 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
11520 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 ssible to set th
11530 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e Serialized [th
11540 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e reading mode] an
11550 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
11560 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
11570 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
11580 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
11590 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
115a0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
115b0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 D configuration
115c0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
115d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
115e0 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e IG_MALLOC]] <dt>
115f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
11600 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
11610 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
11620 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
11630 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
11640 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
11650 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
11660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
11670 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
11680 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
11690 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
116a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
116b0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
116c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
116d0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
116e0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
116f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11700 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
11710 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e into SQLite.)^ ^
11720 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 SQLite makes.**
11730 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
11740 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 copy of the cont
11750 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ent of the [sqli
11760 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
11770 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 structure.** be
11780 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 fore the [sqlite
11790 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 3_config()] call
117a0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a returns.</dd>.*
117b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
117c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d NFIG_GETMALLOC]]
117d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
117e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 IG_GETMALLOC</dt
117f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
11800 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
11810 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
11820 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
11830 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
11840 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
11850 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
11860 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
11870 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
11880 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
11890 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
118a0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
118b0 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 y defined memory
118c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
118d0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 ines.)^.** This
118e0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
118f0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
11900 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 he default memor
11910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
11920 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
11930 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d wrapper that sim
11940 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 ulations memory
11950 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 allocation failu
11960 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 re or.** tracks
11970 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f memory usage, fo
11980 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e r example. </dd>
11990 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
119a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
119b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
119c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f NFIG_MEMSTATUS</
119d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
119e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 s option takes s
119f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
11a00 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 f type int, inte
11a10 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a rpreted as a .**
11a20 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 boolean, which
11a30 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
11a40 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 les the collecti
11a50 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c on of memory all
11a60 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 ocation .** stat
11a70 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d istics. ^(When m
11a80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11a90 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
11aa0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a disabled, the .*
11ab0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 * following SQLi
11ac0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 te interfaces be
11ad0 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 come non-operati
11ae0 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a onal:.** <ul>.
11af0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
11b00 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
11b10 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
11b20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
11b30 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c water()].** <l
11b40 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 i> [sqlite3_soft
11b50 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d _heap_limit64()]
11b60 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
11b70 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a te3_status()].**
11b80 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d </ul>)^.** ^M
11b90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11ba0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
11bb0 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
11bc0 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 lt unless SQLite
11bd0 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
11be0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 with [SQLITE_DEF
11bf0 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d AULT_MEMSTATUS]=
11c00 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 0 in which case
11c10 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
11c20 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
11c30 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
11c40 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 default..** </dd
11c50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
11c60 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
11c70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
11c80 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
11c90 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
11ca0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
11cb0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
11cc0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
11cd0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
11ce0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
11cf0 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 . There are thr
11d00 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 ee arguments: A
11d10 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 pointer an 8-by
11d20 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 te.** aligned me
11d30 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d mory buffer from
11d40 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 which the scrat
11d50 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 ch allocations w
11d60 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c ill be.** drawn,
11d70 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
11d80 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 h scratch alloca
11d90 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e tion (sz),.** an
11da0 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d the maximum nu
11db0 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 mber of scratch
11dc0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e allocations (N).
11dd0 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 The sz.** argu
11de0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d ment must be a m
11df0 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a ultiple of 16..*
11e00 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
11e10 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
11e20 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
11e30 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
11e40 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
11e50 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
11e60 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
11e70 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d te will use no m
11e80 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 ore than two scr
11e90 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 atch buffers per
11ea0 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 thread. So.**
11eb0 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 N should be set
11ec0 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 to twice the exp
11ed0 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 ected maximum nu
11ee0 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e mber of threads.
11ef0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
11f00 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 never require a
11f10 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
11f20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 that is more tha
11f30 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 n 6.** times the
11f40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 database page s
11f50 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 ize. ^If SQLite
11f60 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 needs needs addi
11f70 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 tional.** scratc
11f80 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 h memory beyond
11f90 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
11fa0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 by this configu
11fb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 ration option, t
11fc0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hen .** [sqlite3
11fd0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 _malloc()] will
11fe0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
11ff0 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 n the memory nee
12000 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ded.</dd>.**.**
12010 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12020 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e PAGECACHE]] <dt>
12030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
12040 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 GECACHE</dt>.**
12050 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
12060 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
12070 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
12080 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
12090 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 an use for.** th
120a0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
120b0 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 cache with the d
120c0 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 efault page cach
120d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
120e0 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 . .** This conf
120f0 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 iguration should
12100 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 not be used if
12110 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
12120 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 efine page.** ca
12130 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
12140 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 on is loaded usi
12150 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f ng the SQLITE_CO
12160 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 NFIG_PCACHE2 opt
12170 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ion..** There ar
12180 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
12190 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
121a0 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 : A pointer to 8
121b0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a -byte aligned.**
121c0 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a memory, the siz
121d0 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 e of each page b
121e0 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 uffer (sz), and
121f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
12200 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 ges (N)..** The
12210 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 sz argument shou
12220 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f ld be the size o
12230 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
12240 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 tabase page.** (
12250 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 a power of two b
12260 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 etween 512 and 3
12270 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 2768) plus a lit
12280 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 tle extra for ea
12290 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 ch.** page heade
122a0 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 r. ^The page he
122b0 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 ader size is 20
122c0 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 to 40 bytes depe
122d0 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 nding on.** the
122e0 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 host architectur
122f0 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c e. ^It is harml
12300 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 ess, apart from
12310 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 the wasted memor
12320 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a y,.** to make sz
12330 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 a little too la
12340 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a rge. The first.
12350 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
12360 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 ld point to an a
12370 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 llocation of at
12380 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
12390 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e of memory..** ^
123a0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
123b0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 the memory provi
123c0 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ded by the first
123d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 argument to sat
123e0 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f isfy its.** memo
123f0 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 ry needs for the
12400 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 first N pages t
12410 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 hat it adds to c
12420 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 ache. ^If addit
12430 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 ional.** page ca
12440 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 che memory is ne
12450 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 eded beyond what
12460 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
12470 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 this option, the
12480 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 n.** SQLite goes
12490 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
124a0 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 loc()] for the a
124b0 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 dditional storag
124c0 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 e space..** The
124d0 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 pointer in the f
124e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
124f0 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 st.** be aligned
12500 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f to an 8-byte bo
12510 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 undary or subseq
12520 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 uent behavior of
12530 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
12540 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 be undefined.</d
12550 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12560 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 E_CONFIG_HEAP]]
12570 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
12580 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c G_HEAP</dt>.** <
12590 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
125a0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
125b0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
125c0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 r that SQLite wi
125d0 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c ll use.** for al
125e0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 l of its dynamic
125f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12600 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 on needs beyond
12610 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a those provided.*
12620 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 * for by [SQLITE
12630 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
12640 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e and [SQLITE_CON
12650 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
12660 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 ** There are thr
12670 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e ee arguments: An
12680 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
12690 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
126a0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 emory,.** the nu
126b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
126c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 the memory buff
126d0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 er, and the mini
126e0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
126f0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ize..** ^If the
12700 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
12710 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
12720 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e r) is NULL, then
12730 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a SQLite reverts.
12740 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 ** to using its
12750 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
12760 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 llocator (the sy
12770 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d stem malloc() im
12780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a plementation),.*
12790 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 * undoing any pr
127a0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ior invocation o
127b0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
127c0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 _MALLOC]. ^If t
127d0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 he.** memory poi
127e0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
127f0 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c and either [SQL
12800 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
12810 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 S3] or.** [SQLIT
12820 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 E_ENABLE_MEMSYS5
12830 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 ] are defined, t
12840 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 hen the alternat
12850 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ive memory.** al
12860 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 locator is engag
12870 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c ed to handle all
12880 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f of SQLites memo
12890 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
128a0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 eds..** The firs
128b0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
128c0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d emory pointer) m
128d0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
128e0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 o an 8-byte.** b
128f0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 oundary or subse
12900 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f quent behavior o
12910 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 f SQLite will be
12920 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
12930 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
12940 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 ation size is ca
12950 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 pped at 2**12. R
12960 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 easonable values
12970 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 .** for the mini
12980 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
12990 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 ize are 2**5 thr
129a0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a ough 2**8.</dd>.
129b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
129c0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 ONFIG_MUTEX]] <d
129d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
129e0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
129f0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
12a00 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
12a10 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
12a20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
12a30 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
12a40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
12a50 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
12a60 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
12a70 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
12a80 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
12a90 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 ow-level mutex r
12aa0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
12ab0 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 ed in place.** t
12ac0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 he mutex routine
12ad0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
12ae0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ite.)^ ^SQLite
12af0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
12b00 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f the.** content o
12b10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
12b20 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
12b30 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 ructure before t
12b40 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 he call to.** [s
12b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
12b60 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 returns. ^If SQ
12b70 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
12b80 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
12b90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
12ba0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
12bb0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
12bc0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
12bd0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
12be0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
12bf0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
12c00 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
12c10 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
12c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
12c30 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
12c40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
12c50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12c60 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
12c70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
12c80 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
12c90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12ca0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 GETMUTEX]] <dt>S
12cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
12cc0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
12cd0 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
12ce0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
12cf0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
12d00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
12d10 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
12d20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
12d30 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
12d40 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 ucture. The.**
12d50 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
12d60 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
12d70 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
12d80 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
12d90 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 y defined mutex
12da0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 routines.)^.** T
12db0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
12dc0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
12dd0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
12de0 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a utex allocation.
12df0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
12e00 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 a wrapper used
12e10 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 to track mutex u
12e20 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d sage for perform
12e30 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e ance.** profilin
12e40 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f g or testing, fo
12e50 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 r example. ^If
12e60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
12e70 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
12e80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
12e90 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
12ea0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
12eb0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
12ec0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 en.** the entire
12ed0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 mutexing subsys
12ee0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 tem is omitted f
12ef0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e rom the build an
12f00 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f d hence calls to
12f10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
12f20 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 fig()] with the
12f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
12f40 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 TMUTEX configura
12f50 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
12f60 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
12f70 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
12f80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
12f90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
12fa0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12fb0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
12fc0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
12fd0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
12fe0 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 wo arguments tha
12ff0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 t determine the
13000 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 default.** memor
13010 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 y allocation for
13020 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d the lookaside m
13030 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
13040 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 on each.** [data
13050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
13060 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
13070 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
13080 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f size of each loo
13090 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c kaside buffer sl
130a0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ot and the secon
130b0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
130c0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f of.** slots allo
130d0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 cated to each da
130e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
130f0 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 n.)^ ^(This opt
13100 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
13110 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c <i>default</i> l
13120 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 ookaside size. T
13130 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e he [SQLITE_DBCON
13140 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a FIG_LOOKASIDE].*
13150 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 * verb to [sqlit
13160 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
13170 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
13180 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
13190 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 ide.** configura
131a0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 tion on individu
131b0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 al connections.)
131c0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
131d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
131e0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
131f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
13200 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 2</dt>.** <dd> ^
13210 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
13220 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13230 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
13240 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e pointer to.** an
13250 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
13260 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
13270 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 t. This object
13280 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e specifies the in
13290 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 terface.** to a
132a0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 custom page cach
132b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
132c0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b .)^ ^SQLite mak
132d0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
132e0 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 .** object and u
132f0 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 ses it for page
13300 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c cache memory all
13310 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a ocations.</dd>.*
13320 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
13330 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d NFIG_GETPCACHE2]
13340 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13350 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f FIG_GETPCACHE2</
13360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
13370 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
13380 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
13390 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
133a0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
133b0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
133c0 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 thods2] object.
133d0 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f SQLite copies o
133e0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a f the current.**
133f0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
13400 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 ementation into
13410 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c that object.)^ <
13420 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
13430 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d ITE_CONFIG_LOG]]
13440 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
13450 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c IG_LOG</dt>.** <
13460 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 dd> The SQLITE_C
13470 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e ONFIG_LOG option
13480 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 is used to conf
13490 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 igure the SQLite
134a0 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f .** global [erro
134b0 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 5b 5e 54 68 65 r log]..** [^The
134c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
134d0 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 OG option takes
134e0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 two arguments: a
134f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a pointer to a.**
13500 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
13510 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 call signature
13520 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a of void(*)(void*
13530 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
13540 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 ), .** and a poi
13550 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 nter to void. ^I
13560 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 f the function p
13570 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
13580 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 LL, it is.** inv
13590 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oked by [sqlite3
135a0 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 _log()] to proce
135b0 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 ss each logging
135c0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a event. ^If the.
135d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e ** function poin
135e0 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ter is NULL, the
135f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
13600 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d interface becom
13610 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e es a no-op..** ^
13620 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 The void pointer
13630 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 that is the sec
13640 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
13650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
13660 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 G is.** passed t
13670 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 hrough as the fi
13680 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
13690 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
136a0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a -defined logger.
136b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e ** function when
136c0 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 ever that functi
136d0 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 on is invoked.
136e0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
136f0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
13700 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 logger function
13710 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
13720 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
13730 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f to the correspo
13740 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 nding.** [sqlite
13750 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 3_log()] call an
13760 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f d is intended to
13770 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f be a [result co
13780 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 de] or an.** [ex
13790 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
137a0 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 de]. ^The third
137b0 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
137c0 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 d to the logger
137d0 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 is.** log messag
137e0 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 e after formatti
137f0 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f ng via [sqlite3_
13800 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 snprintf()]..**
13810 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 The SQLite loggi
13820 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ng interface is
13830 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 not reentrant; t
13840 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
13850 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 on.** supplied b
13860 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
13870 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b n must not invok
13880 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 e any SQLite int
13890 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 erface..** In a
138a0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 multi-threaded a
138b0 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 pplication, the
138c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
138d0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 ned logger.** fu
138e0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 nction must be t
138f0 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e hreadsafe. </dd>
13900 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
13910 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 CONFIG_URI]] <dt
13920 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 >SQLITE_CONFIG_U
13930 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 RI.** <dd> This
13940 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
13950 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
13960 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e f type int. If n
13970 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a on-zero, then.**
13980 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 URI handling is
13990 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 globally enable
139a0 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 d. If the parame
139b0 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 ter is zero, the
139c0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a n URI handling.*
139d0 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 * is globally di
139e0 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 sabled. If URI h
139f0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
13a00 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c lly enabled, all
13a10 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 filenames.** pa
13a20 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
13a30 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
13a40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b e3_open_v2()], [
13a50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
13a60 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 ] or.** specifie
13a70 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 d as part of [AT
13a80 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 TACH] commands a
13a90 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 re interpreted a
13aa0 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 s URIs, regardle
13ab0 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 ss.** of whether
13ac0 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c or not the [SQL
13ad0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
13ae0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 ag is set when t
13af0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
13b00 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 onnection is ope
13b10 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c ned. If it is gl
13b20 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c obally disabled,
13b30 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a filenames are.*
13b40 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 * only interpret
13b50 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 ed as URIs if th
13b60 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 e SQLITE_OPEN_UR
13b70 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 I flag is set wh
13b80 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 en the.** databa
13b90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
13ba0 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 opened. By defa
13bb0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e ult, URI handlin
13bc0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a g is globally.**
13bd0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 disabled. The d
13be0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 efault value may
13bf0 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 be changed by c
13c00 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 ompiling with th
13c10 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 e.** [SQLITE_USE
13c20 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 _URI] symbol def
13c30 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ined..**.** [[SQ
13c40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
13c50 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
13c60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13c70 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
13c80 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 EX_SCAN.** <dd>
13c90 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
13ca0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 s a single integ
13cb0 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 er argument whic
13cc0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
13cd0 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e as.** a boolean
13ce0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 in order to ena
13cf0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
13d00 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 he use of coveri
13d10 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a ng indices for.*
13d20 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 * full table sca
13d30 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 ns in the query
13d40 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 optimizer. The
13d50 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
13d60 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a is determined.**
13d70 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
13d80 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 ALLOW_COVERING_I
13d90 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 NDEX_SCAN] compi
13da0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
13db0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 or is "on".** if
13dc0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 that compile-ti
13dd0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 me option is omi
13de0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 tted..** The abi
13df0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 lity to disable
13e00 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 the use of cover
13e10 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 ing indices for
13e20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 full table scans
13e30 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 .** is because s
13e40 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ome incorrectly
13e50 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 coded legacy app
13e60 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lications might
13e70 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d malfunction.** m
13e80 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 alfunction when
13e90 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e the optimization
13ea0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 is enabled. Pr
13eb0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c oviding the abil
13ec0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c ity to.** disabl
13ed0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 e the optimizati
13ee0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c on allows the ol
13ef0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 der, buggy appli
13f00 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 cation code to w
13f10 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 ork.** without c
13f20 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 hange even with
13f30 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
13f40 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
13f50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13f60 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 PCACHE]] [[SQLIT
13f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
13f80 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 HE]].** <dt>SQLI
13f90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
13fa0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 and SQLITE_CONF
13fb0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 IG_GETPCACHE.**
13fc0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f <dd> These optio
13fd0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 ns are obsolete
13fe0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 and should not b
13ff0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f e used by new co
14000 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 de..** They are
14010 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 retained for bac
14020 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
14030 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 lity but are now
14040 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 no-ops..** </dd
14050 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14060 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d _CONFIG_SQLLOG]]
14070 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
14080 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 ONFIG_SQLLOG.**
14090 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
140a0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
140b0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 e if sqlite is c
140c0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
140d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
140e0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 LE_SQLLOG] pre-p
140f0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 rocessor macro d
14100 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 efined. The firs
14110 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c t argument shoul
14120 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 d.** be a pointe
14130 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 r to a function
14140 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 of type void(*)(
14150 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 void*,sqlite3*,c
14160 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 onst char*, int)
14170 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
14180 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 should be of typ
14190 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 e (void*). The c
141a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
141b0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 ed by the librar
141c0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 y.** in three se
141d0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 parate circumsta
141e0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 nces, identified
141f0 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 by the value pa
14200 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 ssed as the.** f
14210 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e ourth parameter.
14220 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 If the fourth p
14230 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 arameter is 0, t
14240 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
14250 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 connection.** p
14260 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
14270 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 ond argument has
14280 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 just been opene
14290 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 d. The third arg
142a0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 ument.** points
142b0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 to a buffer cont
142c0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 aining the name
142d0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 of the main data
142e0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 base file. If th
142f0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 e.** fourth para
14300 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e meter is 1, then
14310 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
14320 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 nt that the thir
14330 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 d parameter.** p
14340 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 oints to has jus
14350 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e t been executed.
14360 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 Or, if the four
14370 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
14380 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 2, then.** the c
14390 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 onnection being
143a0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
143b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
143c0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 s being closed.
143d0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 The.** third par
143e0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 ameter is passed
143f0 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 NULL In this ca
14400 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 se. An example
14410 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a of using this.**
14420 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14430 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 ption can be see
14440 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 n in the "test_s
14450 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 qllog.c" source
14460 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 file in.** the c
14470 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 anonical SQLite
14480 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 source tree.</dd
14490 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
144a0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a _CONFIG_MMAP_SIZ
144b0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 E]].** <dt>SQLIT
144c0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
144d0 5a 45 0a 2a 2a 20 3c 64 64 3e 53 51 4c 49 54 45 ZE.** <dd>SQLITE
144e0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a _CONFIG_MMAP_SIZ
144f0 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 E takes two 64-b
14500 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 it integer (sqli
14510 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 te3_int64) value
14520 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 s.** that are th
14530 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 e default mmap s
14540 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 ize limit (the d
14550 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 efault setting f
14560 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d or.** [PRAGMA mm
14570 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 ap_size]) and th
14580 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
14590 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 d mmap size limi
145a0 74 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c t..** The defaul
145b0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 t setting can be
145c0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 overridden by e
145d0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
145e0 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a nection using.**
145f0 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 either the [PRA
14600 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 GMA mmap_size] c
14610 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 ommand, or by us
14620 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ing the.** [SQLI
14630 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
14640 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c ZE] file control
14650 2e 20 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 . The maximum a
14660 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 llowed mmap size
14670 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 .** cannot be ch
14680 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69 6d anged at run-tim
14690 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65 20 e. Nor may the
146a0 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 maximum allowed
146b0 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78 63 mmap size.** exc
146c0 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d eed the compile-
146d0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 time maximum mma
146e0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 p size set by th
146f0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 e.** [SQLITE_MAX
14700 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 _MMAP_SIZE] comp
14710 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
14720 20 20 0a 2a 2a 20 49 66 20 65 69 74 68 65 72 20 .** If either
14730 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 argument to this
14740 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 option is negat
14750 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 ive, then that a
14760 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 rgument is.** ch
14770 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d anged to its com
14780 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c pile-time defaul
14790 74 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 t..** </dl>.*/.#
147a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
147b0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
147c0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a D 1 /* nil */.
147d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
147e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
147f0 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f D 2 /* nil */
14800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14810 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
14820 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a D 3 /* nil *
14830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
14840 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 _CONFIG_MALLOC
14850 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 4 /* sqli
14860 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a te3_mem_methods*
14870 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14880 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
14890 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 LOC 5 /* sq
148a0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
148b0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
148c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 LITE_CONFIG_SCRA
148d0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 TCH 6 /*
148e0 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 void*, int sz, i
148f0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nt N */.#define
14900 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
14910 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f GECACHE 7 /
14920 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c * void*, int sz,
14930 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e int N */.#defin
14940 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14950 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 HEAP 8
14960 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e /* void*, int n
14970 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f Byte, int min */
14980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14990 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
149a0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 9 /* boole
149b0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 an */.#define SQ
149c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
149d0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 X 10 /*
149e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
149f0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
14a00 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14a10 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 GETMUTEX 11
14a20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
14a30 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a x_methods* */./*
14a40 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 previously SQLI
14a50 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 TE_CONFIG_CHUNKA
14a60 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 LLOC 12 which is
14a70 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 now unused. */
14a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14a90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
14aa0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 13 /* int i
14ab0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
14ac0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14ad0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 HE 14 /*
14ae0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 no-op */.#define
14af0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
14b00 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 ETPCACHE 15
14b10 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
14b20 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14b30 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 G_LOG 1
14b40 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 6 /* xFunc, voi
14b50 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 d* */.#define SQ
14b60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 LITE_CONFIG_URI
14b70 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 17 /*
14b80 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
14b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
14ba0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a CHE2 18 /*
14bb0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
14bc0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
14bd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
14be0 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 IG_GETPCACHE2
14bf0 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 19 /* sqlite3_p
14c00 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 cache_methods2*
14c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14c20 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e E_CONFIG_COVERIN
14c30 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 G_INDEX_SCAN 20
14c40 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 /* int */.#defi
14c50 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
14c60 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 _SQLLOG 21
14c70 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f /* xSqllog, vo
14c80 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
14c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
14ca0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a P_SIZE 22 /*
14cb0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 sqlite3_int64,
14cc0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f sqlite3_int64 */
14cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
14ce0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
14cf0 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 ction Configurat
14d00 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a ion Options.**.*
14d10 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
14d20 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 s are the availa
14d30 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 ble integer conf
14d40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14d50 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 s that.** can be
14d60 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
14d70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
14d80 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 o the [sqlite3_d
14d90 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 b_config()] inte
14da0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
14db0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14dc0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
14dd0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
14de0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
14df0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing 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 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
14e20 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
14e30 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
14e40 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
14e50 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
14e60 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
14e70 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
14e80 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
14e90 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 l worked. ^The
14ea0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
14eb0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 ig()] interface
14ec0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a will return a.**
14ed0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 non-zero [error
14ee0 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 code] if a disc
14ef0 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 ontinued or unsu
14f00 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 pported configur
14f10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 ation option.**
14f20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a is invoked..**.*
14f30 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 * <dl>.** <dt>SQ
14f40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
14f50 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
14f60 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
14f70 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 n takes three ad
14f80 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
14f90 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e ts that determin
14fa0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 e the .** [looka
14fb0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f side memory allo
14fc0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 cator] configura
14fd0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 tion for the [da
14fe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14ff0 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 n]..** ^The firs
15000 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 t argument (the
15010 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
15020 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 to [sqlite3_db_c
15030 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a onfig()] is a.**
15040 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 pointer to a me
15050 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 mory buffer to u
15060 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 se for lookaside
15070 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 memory..** ^The
15080 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
15090 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 after the SQLITE
150a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
150b0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 IDE verb.** may
150c0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 be NULL in which
150d0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c case SQLite wil
150e0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a l allocate the.*
150f0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 * lookaside buff
15100 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 er itself using
15110 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
15120 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 )]. ^The second
15130 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a argument is the.
15140 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 ** size of each
15150 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
15160 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 slot. ^The thi
15170 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 rd argument is t
15180 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 he number of.**
15190 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 slots. The size
151a0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 of the buffer i
151b0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
151c0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 ment must be gre
151d0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 ater than.** or
151e0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f equal to the pro
151f0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f duct of the seco
15200 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 nd and third arg
15210 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 uments. The buf
15220 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 fer.** must be a
15230 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
15240 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e yte boundary. ^
15250 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 If the second ar
15260 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c gument to.** SQL
15270 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
15280 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 KASIDE is not a
15290 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 multiple of 8, i
152a0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a t is internally.
152b0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 ** rounded down
152c0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c to the next smal
152d0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 ler multiple of
152e0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 8. ^(The lookas
152f0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f ide memory.** co
15300 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
15310 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
15320 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 ction can only b
15330 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 e changed when t
15340 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f hat.** connectio
15350 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 n is not current
15360 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 ly using lookasi
15370 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e de memory, or in
15380 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 other words.**
15390 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e when the "curren
153a0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 t value" returne
153b0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
153c0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 _db_status](D,[S
153d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
153e0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 KASIDE],...) is
153f0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 zero..** Any att
15400 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 empt to change t
15410 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d he lookaside mem
15420 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ory configuratio
15430 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 n when lookaside
15440 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e .** memory is in
15450 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 use leaves the
15460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e configuration un
15470 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 changed and retu
15480 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f rns .** [SQLITE_
15490 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a BUSY].)^</dd>.**
154a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
154b0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 BCONFIG_ENABLE_F
154c0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e KEY</dt>.** <dd>
154d0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
154e0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 used to enable
154f0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 or disable the e
15500 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a nforcement of.**
15510 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f [foreign key co
15520 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 nstraints]. The
15530 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
15540 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
15550 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
15560 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
15570 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
15580 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
15590 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c FK enforcement,
155a0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 .** positive to
155b0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 enable FK enforc
155c0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 ement or negativ
155d0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e e to leave FK en
155e0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 forcement.** unc
155f0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 hanged. The sec
15600 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
15610 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
15620 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
15630 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
15640 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
15650 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 cate whether FK
15660 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f enforcement is o
15670 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c ff or on.** foll
15680 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
15690 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
156a0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 ameter may be a
156b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
156c0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 .** which case t
156d0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e he FK enforcemen
156e0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 t setting is not
156f0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 reported back.
15700 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
15710 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
15720 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f ENABLE_TRIGGER</
15730 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
15740 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 s option is used
15750 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
15760 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 sable [CREATE TR
15770 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 IGGER | triggers
15780 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 ]..** There shou
15790 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 ld be two additi
157a0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a onal arguments..
157b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
157c0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 ument is an inte
157d0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 ger which is 0 t
157e0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 o disable trigge
157f0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 rs,.** positive
15800 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 to enable trigge
15810 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 rs or negative t
15820 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 o leave the sett
15830 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a ing unchanged..*
15840 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 * The second par
15850 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e ameter is a poin
15860 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
15870 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 r into which.**
15880 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 is written 0 or
15890 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 1 to indicate wh
158a0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 ether triggers a
158b0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 re disabled or e
158c0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nabled.** follow
158d0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
158e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
158f0 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
15900 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
15910 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
15920 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 trigger setting
15930 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
15940 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
15950 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
15960 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
15970 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
15980 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 1001 /* voi
15990 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 d* int int */.#d
159a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
159b0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
159c0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 Y 1002 /* i
159d0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
159e0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
159f0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 IG_ENABLE_TRIGGE
15a00 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 R 1003 /* int
15a10 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 int* */.../*.**
15a20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 CAPI3REF: Enable
15a30 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 Or Disable Exte
15a40 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
15a50 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
15a60 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
15a70 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 sult_codes() rou
15a80 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 tine enables or
15a90 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 disables the.**
15aa0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
15ab0 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 codes] feature
15ac0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 of SQLite. ^The
15ad0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a extended result.
15ae0 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 ** codes are dis
15af0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 abled by default
15b00 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 for historical
15b10 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
15b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 /.int sqlite3_ex
15b30 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f tended_result_co
15b40 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e des(sqlite3*, in
15b50 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a t onoff);../*.**
15b60 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 CAPI3REF: Last
15b70 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a Insert Rowid.**.
15b80 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 ** ^Each entry i
15b90 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c n an SQLite tabl
15ba0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 e has a unique 6
15bb0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 4-bit signed.**
15bc0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c integer key call
15bd0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 ed the [ROWID |
15be0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 "rowid"]. ^The r
15bf0 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 owid is always a
15c00 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 vailable.** as a
15c10 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c n undeclared col
15c20 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c umn named ROWID,
15c30 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f OID, or _ROWID_
15c40 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 as long as thos
15c50 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e e.** names are n
15c60 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 ot also used by
15c70 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 explicitly decla
15c80 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 red columns. ^If
15c90 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 .** the table ha
15ca0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 s a column of ty
15cb0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d pe [INTEGER PRIM
15cc0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 ARY KEY] then th
15cd0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 at column.** is
15ce0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f another alias fo
15cf0 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a r the rowid..**.
15d00 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
15d10 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f returns the [ro
15d20 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 wid] of the most
15d30 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 recent.** succe
15d40 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 ssful [INSERT] i
15d50 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
15d60 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 from the [datab
15d70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
15d80 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
15d90 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f argument. ^As o
15da0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e f SQLite version
15db0 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 3.7.7, this rou
15dc0 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 tines.** records
15dd0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
15de0 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f rowid of both o
15df0 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 rdinary tables a
15e00 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c nd [virtual tabl
15e10 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 es]..** ^If no s
15e20 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
15e30 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 T]s.** have ever
15e40 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 occurred on tha
15e50 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 t database conne
15e60 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 ction, zero is r
15e70 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
15e80 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 (If an [INSERT]
15e90 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 occurs within a
15ea0 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 trigger or withi
15eb0 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 n a [virtual tab
15ec0 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 le].** method, t
15ed0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
15ee0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 will return the
15ef0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
15f00 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 inserted.** row
15f10 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 as long as the t
15f20 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 rigger or virtua
15f30 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 l table method i
15f40 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 s running..** Bu
15f50 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 t once the trigg
15f60 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 er or virtual ta
15f70 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c ble method ends,
15f80 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
15f90 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 ned .** by this
15fa0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 routine reverts
15fb0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 to what it was b
15fc0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 efore the trigge
15fd0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 r or virtual.**
15fe0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 table method beg
15ff0 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 an.)^.**.** ^An
16000 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 [INSERT] that fa
16010 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e ils due to a con
16020 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
16030 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 n is not a.** su
16040 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
16050 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 ] and does not c
16060 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 hange the value
16070 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
16080 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 .** routine. ^T
16090 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 hus INSERT OR FA
160a0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 IL, INSERT OR IG
160b0 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 NORE, INSERT OR
160c0 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 ROLLBACK,.** and
160d0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 INSERT OR ABORT
160e0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 make no changes
160f0 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 to the return v
16100 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 alue of this.**
16110 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 routine when the
16120 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 ir insertion fai
16130 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 ls. ^(When INSE
16140 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a RT OR REPLACE.**
16150 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f encounters a co
16160 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
16170 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 on, it does not
16180 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e fail. The.** IN
16190 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 SERT continues t
161a0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 o completion aft
161b0 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 er deleting rows
161c0 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 that caused.**
161d0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 the constraint p
161e0 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 roblem so INSERT
161f0 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c OR REPLACE will
16200 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a always change.*
16210 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c * the return val
16220 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 ue of this inter
16230 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 face.)^.**.** ^F
16240 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 or the purposes
16250 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c of this routine,
16260 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 an [INSERT] is
16270 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a considered to.**
16280 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 be successful e
16290 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 ven if it is sub
162a0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 sequently rolled
162b0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 back..**.** Thi
162c0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 s function is ac
162d0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 cessible to SQL
162e0 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 statements via t
162f0 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 he.** [last_inse
16300 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 rt_rowid() SQL f
16310 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
16320 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
16330 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 read performs a
16340 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 new [INSERT] on
16350 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 the same.** data
16360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
16370 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 while the [sqlit
16380 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
16390 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 owid()].** funct
163a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 ion is running a
163b0 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 nd thus changes
163c0 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 the last insert
163d0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e [rowid],.** then
163e0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
163f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
16400 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
16410 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 d()] is.** unpre
16420 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 dictable and mig
16430 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 ht not equal eit
16440 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 her the old or t
16450 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 he new.** last i
16460 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a nsert [rowid]..*
16470 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 /.sqlite3_int64
16480 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
16490 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 ert_rowid(sqlite
164a0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 3*);../*.** CAPI
164b0 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 3REF: Count The
164c0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d Number Of Rows M
164d0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 odified.**.** ^T
164e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
164f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
16500 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 of database rows
16510 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 that were chang
16520 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 ed.** or inserte
16530 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 d or deleted by
16540 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c the most recentl
16550 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 y completed SQL
16560 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 statement.** on
16570 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
16580 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
16590 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ied by the first
165a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
165b0 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 (Only changes th
165c0 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 at are directly
165d0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
165e0 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 [INSERT], [UPDA
165f0 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 TE],.** or [DELE
16600 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 TE] statement ar
16610 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 e counted. Auxi
16620 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 liary changes ca
16630 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 used by.** trigg
16640 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 ers or [foreign
16650 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 key actions] are
16660 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 not counted.)^
16670 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 Use the.** [sqli
16680 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
16690 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f s()] function to
166a0 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 find the total
166b0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 number of change
166c0 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 s.** including c
166d0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
166e0 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f triggers and fo
166f0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e reign key action
16700 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 s..**.** ^Change
16710 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 s to a view that
16720 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 are simulated b
16730 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 y an [INSTEAD OF
16740 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 trigger].** are
16750 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f not counted. O
16760 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 nly real table c
16770 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 hanges are count
16780 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 ed..**.** ^(A "r
16790 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 ow change" is a
167a0 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 change to a sing
167b0 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 le row of a sing
167c0 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 le table.** caus
167d0 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c ed by an INSERT,
167e0 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 DELETE, or UPDA
167f0 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 TE statement. R
16800 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 ows that.** are
16810 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 changed as side
16820 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c effects of [REPL
16830 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 ACE] constraint
16840 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 resolution,.** r
16850 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 ollback, ABORT p
16860 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 rocessing, [DROP
16870 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 TABLE], or by a
16880 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 ny other.** mech
16890 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f anisms do not co
168a0 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f unt as direct ro
168b0 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a w changes.)^.**.
168c0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f ** A "trigger co
168d0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 ntext" is a scop
168e0 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 e of execution t
168f0 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a hat begins and.*
16900 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 * ends with the
16910 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 script of a [CRE
16920 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 ATE TRIGGER | tr
16930 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 igger]. .** Most
16940 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
16950 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 are.** evaluated
16960 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 outside of any
16970 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 trigger. This i
16980 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c s the "top level
16990 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e ".** trigger con
169a0 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 text. If a trig
169b0 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 ger fires from t
169c0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a he top level, a.
169d0 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 ** new trigger c
169e0 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 ontext is entere
169f0 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 d for the durati
16a00 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a on of that one.*
16a10 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 * trigger. Subt
16a20 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 riggers create s
16a30 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 ubcontexts for t
16a40 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a heir duration..*
16a50 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 *.** ^Calling [s
16a60 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f qlite3_exec()] o
16a70 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
16a80 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 )] recursively d
16a90 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 oes.** not creat
16aa0 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 e a new trigger
16ab0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e context..**.** ^
16ac0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
16ad0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
16ae0 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 of direct row c
16af0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a hanges in the.**
16b00 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 most recent INS
16b10 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
16b20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
16b30 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
16b40 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 .** trigger cont
16b50 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 ext..**.** ^Thus
16b60 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 , when called fr
16b70 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c om the top level
16b80 2c 20 74 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 0a 2a 2a 20 6e returns the.** n
16ba0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 umber of changes
16bb0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 in the most rec
16bc0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ent INSERT, UPDA
16bd0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
16be0 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 that also occur
16bf0 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c red at the top l
16c00 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 evel. ^(Within
16c10 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 the body of a tr
16c20 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 igger,.** the sq
16c30 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
16c40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
16c50 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 called to find
16c60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
16c70 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 changes in the
16c80 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
16c90 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 mpleted INSERT,
16ca0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
16cb0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 E.** statement w
16cc0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f ithin the body o
16cd0 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 f the same trigg
16ce0 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 er..** However,
16cf0 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 the number retur
16d00 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 ned does not inc
16d10 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 lude changes.**
16d20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 caused by subtri
16d30 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 ggers since thos
16d40 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e e have their own
16d50 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a context.)^.**.*
16d60 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
16d70 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
16d80 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
16d90 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
16da0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
16db0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e ], and the [chan
16dc0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
16dd0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
16de0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
16df0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
16e00 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
16e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
16e20 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
16e30 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
16e40 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
16e50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a alue returned.**
16e60 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
16e70 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
16e80 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c gful..*/.int sql
16e90 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c ite3_changes(sql
16ea0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
16eb0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e API3REF: Total N
16ec0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
16ed0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
16ee0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
16ef0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
16f00 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 f row changes ca
16f10 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d used by [INSERT]
16f20 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 ,.** [UPDATE] or
16f30 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
16f40 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b ents since the [
16f50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16f60 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e ion] was opened.
16f70 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 .** ^(The count
16f80 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
16f90 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
16fa0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c s() includes all
16fb0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d changes.** from
16fc0 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 all [CREATE TRI
16fd0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 GGER | trigger]
16fe0 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 contexts and cha
16ff0 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 nges made by.**
17000 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
17010 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a ions]. However,.
17020 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ** the count doe
17030 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
17040 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d anges used to im
17050 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 plement [REPLACE
17060 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a ] constraints,.*
17070 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f * do rollbacks o
17080 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 r ABORT processi
17090 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 ng, or [DROP TAB
170a0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 LE] processing.
170b0 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f The.** count do
170c0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 es not include r
170d0 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 ows of views tha
170e0 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 t fire an [INSTE
170f0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a AD OF trigger],.
17100 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 ** though if the
17110 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 INSTEAD OF trig
17120 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ger makes change
17130 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 s of its own, th
17140 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 ose changes .**
17150 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a are counted.)^.*
17160 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
17170 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 otal_changes() f
17180 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 unction counts t
17190 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f he changes as so
171a0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 on as.** the sta
171b0 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
171c0 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 s them is comple
171d0 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
171e0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a atement handle.*
171f0 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b * is passed to [
17200 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
17210 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
17220 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a alize()])..**.**
17230 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
17240 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
17250 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
17260 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
17270 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
17280 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 the [total_chang
17290 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
172a0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
172b0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
172c0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
172d0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
172e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
172f0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 while [sqlite3_t
17300 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
17310 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
17320 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
17330 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
17340 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
17350 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e eaningful..*/.in
17360 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f t sqlite3_total_
17370 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
17380 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
17390 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 EF: Interrupt A
173a0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 Long-Running Que
173b0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 ry.**.** ^This f
173c0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 unction causes a
173d0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 ny pending datab
173e0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ase operation to
173f0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 abort and.** re
17400 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c turn at its earl
17410 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 iest opportunity
17420 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 . This routine i
17430 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 s typically.** c
17440 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 alled in respons
17450 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 e to a user acti
17460 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 on such as press
17470 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 ing "Cancel".**
17480 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 or Ctrl-C where
17490 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 the user wants a
174a0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 long query oper
174b0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a ation to halt.**
174c0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
174d0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 .** ^It is safe
174e0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
174f0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 tine from a thre
17500 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f ad different fro
17510 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 m the.** thread
17520 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c that is currentl
17530 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 y running the da
17540 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
17550 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 . But it.** is
17560 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c not safe to call
17570 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
17580 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
17590 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a onnection] that.
175a0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 ** is closed or
175b0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f might close befo
175c0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 re sqlite3_inter
175d0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
175e0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c **.** ^If an SQL
175f0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 operation is ve
17600 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 ry nearly finish
17610 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 ed at the time w
17620 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 hen.** sqlite3_i
17630 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 nterrupt() is ca
17640 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 lled, then it mi
17650 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 ght not have an
17660 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 opportunity.** t
17670 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 o be interrupted
17680 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 and might conti
17690 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f nue to completio
176a0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c n..**.** ^An SQL
176b0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
176c0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 is interrupted w
176d0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
176e0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a TE_INTERRUPT]..*
176f0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 * ^If the interr
17700 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 upted SQL operat
17710 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 ion is an INSERT
17720 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
17730 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ETE.** that is i
17740 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 nside an explici
17750 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
17760 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 hen the entire t
17770 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 ransaction.** wi
17780 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ll be rolled bac
17790 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
177a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
177b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 te3_interrupt(D)
177c0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 call is in effe
177d0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 ct until all cur
177e0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a rently running.*
177f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
17800 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
17810 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 nnection] D comp
17820 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 lete. ^Any new
17830 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
17840 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
17850 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
17860 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
17870 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 call and before
17880 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 the .** running
17890 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 statements reac
178a0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 hes zero are int
178b0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 errupted as if t
178c0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 hey had been.**
178d0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f running prior to
178e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
178f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 errupt() call.
17900 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 ^New SQL stateme
17910 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
17920 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
17930 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d e running statem
17940 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 ent count reache
17950 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f s zero are.** no
17960 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 t effected by th
17970 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
17980 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c upt()..** ^A cal
17990 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 l to sqlite3_int
179a0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f errupt(D) that o
179b0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 ccurs when there
179c0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a are no running.
179d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
179e0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 s is a no-op and
179f0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f has no effect o
17a00 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 n SQL statements
17a10 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
17a20 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 rted after the s
17a30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
17a40 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e () call returns.
17a50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 .**.** If the da
17a60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17a70 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b n closes while [
17a80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
17a90 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 t()].** is runni
17aa0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e ng then bad thin
17ab0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 gs will likely h
17ac0 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 appen..*/.void s
17ad0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
17ae0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
17af0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
17b00 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
17b10 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f Statement Is Co
17b20 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 mplete.**.** The
17b30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
17b40 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f useful during co
17b50 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 mmand-line input
17b60 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 to determine if
17b70 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c the.** currentl
17b80 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 y entered text s
17b90 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 eems to form a c
17ba0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
17bb0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 ement or.** if a
17bc0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 dditional input
17bd0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 is needed before
17be0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 sending the tex
17bf0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 t into.** SQLite
17c00 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e for parsing. ^
17c10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
17c20 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 eturn 1 if the i
17c30 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 nput string.** a
17c40 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 ppears to be a c
17c50 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 omplete SQL stat
17c60 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 ement. ^A state
17c70 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 ment is judged t
17c80 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 o be.** complete
17c90 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 if it ends with
17ca0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b a semicolon tok
17cb0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 en and is not a
17cc0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 prefix of a.** w
17cd0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 ell-formed CREAT
17ce0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d E TRIGGER statem
17cf0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e ent. ^Semicolon
17d00 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 s that are embed
17d10 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 ded within.** st
17d20 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 ring literals or
17d30 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 quoted identifi
17d40 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d er names or comm
17d50 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 ents are not.**
17d60 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 independent toke
17d70 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 ns (they are par
17d80 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 t of the token i
17d90 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 n which they are
17da0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e .** embedded) an
17db0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f d thus do not co
17dc0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 unt as a stateme
17dd0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 nt terminator.
17de0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 ^Whitespace.** a
17df0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 nd comments that
17e00 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 follow the fina
17e10 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 l semicolon are
17e20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
17e30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
17e40 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 eturn 0 if the s
17e50 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f tatement is inco
17e60 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a mplete. ^If a.*
17e70 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
17e80 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 ion fails, then
17e90 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 SQLITE_NOMEM is
17ea0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
17eb0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
17ec0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 do not parse the
17ed0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
17ee0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 thus.** will not
17ef0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 detect syntacti
17f00 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 cally incorrect
17f10 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 SQL..**.** ^(If
17f20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 SQLite has not b
17f30 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 een initialized
17f40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 using [sqlite3_i
17f50 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 nitialize()] pri
17f60 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 or .** to invoki
17f70 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c ng sqlite3_compl
17f80 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c ete16() then sql
17f90 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
17fa0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
17fb0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
17fc0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
17fd0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 e16(). If that
17fe0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 initialization f
17ff0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ails,.** then th
18000 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
18010 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 rom sqlite3_comp
18020 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 lete16() will be
18030 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 non-zero.** reg
18040 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
18050 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e er or not the in
18060 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c put SQL is compl
18070 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ete.)^.**.** The
18080 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
18090 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d e3_complete()] m
180a0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 ust be a zero-te
180b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
180c0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 8 string..**.**
180d0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
180e0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
180f0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
18100 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
18110 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 UTF-16 string i
18120 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 n native byte or
18130 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 der..*/.int sqli
18140 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
18150 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 st char *sql);.i
18160 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c nt sqlite3_compl
18170 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 ete16(const void
18180 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 *sql);../*.** C
18190 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 API3REF: Registe
181a0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 r A Callback To
181b0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 Handle SQLITE_BU
181c0 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 SY Errors.**.**
181d0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 ^This routine se
181e0 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 ts a callback fu
181f0 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 nction that migh
18200 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 t be invoked whe
18210 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 never.** an atte
18220 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f mpt is made to o
18230 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 pen a database t
18240 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 able that anothe
18250 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 r thread.** or p
18260 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 rocess has locke
18270 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
18280 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
18290 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 s NULL, then [SQ
182a0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 LITE_BUSY] or [S
182b0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
182c0 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 KED].** is retur
182d0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 ned immediately
182e0 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e upon encounterin
182f0 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 g the lock. ^If
18300 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
18310 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c ck.** is not NUL
18320 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c L, then the call
18330 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e back might be in
18340 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
18350 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
18360 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
18370 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 ent to the busy
18380 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
18390 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
183a0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
183b0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
183c0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
183d0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
183e0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ^The second ar
183f0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
18400 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 busy handler ca
18410 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 llback is the nu
18420 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
18430 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 at the busy hand
18440 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 ler has.** been
18450 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 invoked for this
18460 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 locking event.
18470 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 ^If the.** busy
18480 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
18490 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 s 0, then no add
184a0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 itional attempts
184b0 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 are made to.**
184c0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
184d0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f ase and [SQLITE_
184e0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
184f0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 _IOERR_BLOCKED]
18500 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 is returned..**
18510 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
18520 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
18530 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 o, then another
18540 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 attempt.** is ma
18550 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 de to open the d
18560 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 atabase for read
18570 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c ing and the cycl
18580 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a e repeats..**.**
18590 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 The presence of
185a0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 a busy handler
185b0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 does not guarant
185c0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 ee that it will
185d0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 be invoked.** wh
185e0 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b en there is lock
185f0 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 contention. ^If
18600 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e SQLite determin
18610 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 es that invoking
18620 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e the busy.** han
18630 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c dler could resul
18640 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c t in a deadlock,
18650 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 it will go ahea
18660 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 d and return [SQ
18670 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 LITE_BUSY].** or
18680 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
18690 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 LOCKED] instead
186a0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 of invoking the
186b0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
186c0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e Consider a scen
186d0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 ario where one p
186e0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
186f0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 g a read lock th
18700 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 at.** it is tryi
18710 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ng to promote to
18720 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
18730 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 and.** a second
18740 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
18750 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c ing a reserved l
18760 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 ock that it is t
18770 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d rying.** to prom
18780 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 ote to an exclus
18790 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 ive lock. The f
187a0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e irst process can
187b0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 not proceed.** b
187c0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
187d0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f cked by the seco
187e0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nd and the secon
187f0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 d process cannot
18800 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 .** proceed beca
18810 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
18820 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 d by the first.
18830 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 If both process
18840 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 es.** invoke the
18850 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 busy handlers,
18860 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b neither will mak
18870 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 e any progress.
18880 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 Therefore,.** S
18890 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 QLite returns [S
188a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 QLITE_BUSY] for
188b0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
188c0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 s, hoping that t
188d0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 his.** will indu
188e0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f ce the first pro
188f0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 cess to release
18900 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e its read lock an
18910 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 d allow.** the s
18920 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f econd process to
18930 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 proceed..**.**
18940 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 ^The default bus
18950 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
18960 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b LL..**.** ^The [
18970 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 SQLITE_BUSY] err
18980 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 or is converted
18990 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 to [SQLITE_IOERR
189a0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 _BLOCKED].** whe
189b0 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 n SQLite is in t
189c0 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c he middle of a l
189d0 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e arge transaction
189e0 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a where all the.*
189f0 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e * changes will n
18a00 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 ot fit into the
18a10 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e in-memory cache.
18a20 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a SQLite will.**
18a30 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 already hold a
18a40 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e RESERVED lock on
18a50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
18a60 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 le, but it needs
18a70 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 .** to promote t
18a80 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c his lock to EXCL
18a90 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 USIVE so that it
18aa0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 can spill cache
18ab0 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 .** pages into t
18ac0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
18ad0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f without harm to
18ae0 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 concurrent.** r
18af0 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 eaders. ^If it
18b00 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f is unable to pro
18b10 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 mote the lock, t
18b20 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 hen the in-memor
18b30 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 y.** cache will
18b40 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e be left in an in
18b50 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 consistent state
18b60 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f and so the erro
18b70 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f r.** code is pro
18b80 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 moted from the r
18b90 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e elatively benign
18ba0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 [SQLITE_BUSY] t
18bb0 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 o.** the more se
18bc0 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 vere [SQLITE_IOE
18bd0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 RR_BLOCKED]. ^T
18be0 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 his error code p
18bf0 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 romotion.** forc
18c00 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 es an automatic
18c10 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 rollback of the
18c20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 changes. See th
18c30 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 e.** <a href="/c
18c40 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f vstrac/wiki?p=Co
18c50 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e rruptionFollowin
18c60 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 gBusyError">.**
18c70 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 CorruptionFollow
18c80 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e ingBusyError</a>
18c90 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 wiki page for a
18ca0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 discussion of w
18cb0 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d hy.** this is im
18cc0 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e portant..**.** ^
18cd0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
18ce0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
18cf0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 handler defined
18d00 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 for each.** [da
18d10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18d20 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e n]. Setting a n
18d30 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 ew busy handler
18d40 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 clears any.** pr
18d50 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e eviously set han
18d60 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 dler.)^ ^Note t
18d70 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c hat calling [sql
18d80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
18d90 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 t()].** will als
18da0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 o set or clear t
18db0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
18dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 .**.** The busy
18dd0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 callback should
18de0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 not take any act
18df0 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 ions which modif
18e00 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 y the.** databas
18e10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
18e20 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
18e30 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 sy handler. Any
18e40 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a such actions.**
18e50 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
18e60 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a ined behavior..*
18e70 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e * .** A busy han
18e80 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c dler must not cl
18e90 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ose the database
18ea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
18eb0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
18ec0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
18ed0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
18ee0 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c dler..*/.int sql
18ef0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
18f00 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 r(sqlite3*, int(
18f10 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 *)(void*,int), v
18f20 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
18f30 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 PI3REF: Set A Bu
18f40 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a sy Timeout.**.**
18f50 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 ^This routine s
18f60 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 ets a [sqlite3_b
18f70 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 usy_handler | bu
18f80 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 sy handler] that
18f90 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 sleeps.** for a
18fa0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e specified amoun
18fb0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 t of time when a
18fc0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 table is locked
18fd0 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a . ^The handler.
18fe0 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 ** will sleep mu
18ff0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 ltiple times unt
19000 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 il at least "ms"
19010 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
19020 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 sleeping.** hav
19030 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 e accumulated.
19040 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 ^After at least
19050 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 "ms" millisecond
19060 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a s of sleeping,.*
19070 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 * the handler re
19080 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 turns 0 which ca
19090 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 uses [sqlite3_st
190a0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a ep()] to return.
190b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
190c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
190d0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a R_BLOCKED]..**.*
190e0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 * ^Calling this
190f0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
19100 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
19110 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
19120 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
19130 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
19140 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 rs..**.** ^(Ther
19150 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
19160 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
19170 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
19180 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
19190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
191a0 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 y any given mome
191b0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 nt. If another
191c0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 busy handler.**
191d0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 was defined (us
191e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
191f0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 y_handler()]) pr
19200 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a ior to calling.*
19210 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 * this routine,
19220 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 that other busy
19230 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 handler is clear
19240 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c ed.)^.*/.int sql
19250 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
19260 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
19270 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ms);../*.** CAPI
19280 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 3REF: Convenienc
19290 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 e Routines For R
192a0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a unning Queries.*
192b0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c *.** This is a l
192c0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 egacy interface
192d0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 that is preserve
192e0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
192f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
19300 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e * Use of this in
19310 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 terface is not r
19320 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a ecommended..**.*
19330 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 * Definition: A
19340 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c <b>result table<
19350 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 /b> is memory da
19360 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 ta structure cre
19370 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b ated by the.** [
19380 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
19390 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 e()] interface.
193a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
193b0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 records the.** c
193c0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 omplete query re
193d0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f sults from one o
193e0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a r more queries..
193f0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 **.** The table
19400 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 conceptually has
19410 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 a number of row
19420 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 s and columns.
19430 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d But.** these num
19440 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 bers are not par
19450 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 t of the result
19460 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 table itself. T
19470 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 hese.** numbers
19480 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 are obtained sep
19490 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 arately. Let N
194a0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
194b0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 rows.** and M b
194c0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 e the number of
194d0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 columns..**.** A
194e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 result table is
194f0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
19500 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 nters to zero-te
19510 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
19520 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 trings..** There
19530 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 are (N+1)*M ele
19540 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 ments in the arr
19550 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d ay. The first M
19560 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a pointers point.
19570 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 ** to zero-termi
19580 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
19590 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 at contain the
195a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c names of the col
195b0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d umns..** The rem
195c0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 aining entries a
195d0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 ll point to quer
195e0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c y results. NULL
195f0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a values result.*
19600 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 * in NULL pointe
19610 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 rs. All other v
19620 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 alues are in the
19630 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 ir UTF-8 zero-te
19640 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
19650 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f ng representatio
19660 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 n as returned by
19670 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
19680 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _text()]..**.**
19690 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d A result table m
196a0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 ight consist of
196b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f one or more memo
196c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a ry allocations..
196d0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 ** It is not saf
196e0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 e to pass a resu
196f0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c lt table directl
19700 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 y to [sqlite3_fr
19710 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 ee()]..** A resu
19720 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 lt table should
19730 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 be deallocated u
19740 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 sing [sqlite3_fr
19750 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a ee_table()]..**.
19760 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 ** ^(As an examp
19770 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 le of the result
19780 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 table format, s
19790 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 uppose a query r
197a0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 esult.** is as f
197b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
197c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
197d0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 ** Name
197e0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 | Age.**
197f0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------
19800 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a -------------.**
19810 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 Alice
19820 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 | 43.**
19830 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c Bob |
19840 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 28.** Ci
19850 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a ndy | 21.*
19860 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
19870 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 uote>.**.** Ther
19880 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e e are two column
19890 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 (M==2) and thre
198a0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 e rows (N==3).
198b0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 Thus the.** resu
198c0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 lt table has 8 e
198d0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 ntries. Suppose
198e0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
198f0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 e is stored.** i
19900 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 n an array names
19910 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e azResult. Then
19920 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 azResult holds
19930 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a this content:.**
19940 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
19950 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
19960 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 azResult[0]
19970 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 = "Name";.**
19980 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
19990 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 ;1] = "Age";.**
199a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
199b0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 #91;2] = "Alice"
199c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
199d0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 sult[3] = "4
199e0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 3";.** az
199f0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 Result[4] =
19a00 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Bob";.**
19a10 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d azResult[5]
19a20 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 = "28";.**
19a30 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
19a40 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 6] = "Cindy";.**
19a50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
19a60 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a [7] = "21";.
19a70 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
19a80 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e quote>)^.**.** ^
19a90 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
19aa0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e table() function
19ab0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f evaluates one o
19ac0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f r more.** semico
19ad0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 lon-separated SQ
19ae0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 L statements in
19af0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
19b00 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 ted UTF-8.** str
19b10 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 ing of its 2nd p
19b20 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
19b30 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 urns a result ta
19b40 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f ble to the.** po
19b50 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 inter given in i
19b60 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
19b70 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 ..**.** After th
19b80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 e application ha
19b90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
19ba0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 the result from
19bb0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
19bc0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 e(),.** it must
19bd0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 pass the result
19be0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f table pointer to
19bf0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
19c00 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 ble() in order t
19c10 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 o.** release the
19c20 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 memory that was
19c30 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 malloced. Beca
19c40 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 use of the way t
19c50 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
19c60 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 alloc()] happens
19c70 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f within sqlite3_
19c80 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 get_table(), the
19c90 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 calling.** func
19ca0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 tion must not tr
19cb0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 y to call [sqlit
19cc0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 e3_free()] direc
19cd0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 tly. Only.** [s
19ce0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
19cf0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 e()] is able to
19d00 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
19d10 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 ry properly and
19d20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 safely..**.** Th
19d30 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
19d40 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
19d50 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 is implemented a
19d60 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 s a wrapper arou
19d70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 nd.** [sqlite3_e
19d80 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c xec()]. The sql
19d90 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
19da0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f routine does no
19db0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a t have access.**
19dc0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c to any internal
19dd0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 data structures
19de0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 of SQLite. It
19df0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 uses only the pu
19e00 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 blic.** interfac
19e10 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 e defined here.
19e20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 As a consequenc
19e30 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f e, errors that o
19e40 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 ccur in the.** w
19e50 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 rapper layer out
19e60 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 side of the inte
19e70 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 rnal [sqlite3_ex
19e80 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e ec()] call are n
19e90 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 ot.** reflected
19ea0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
19eb0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
19ec0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a errcode()] or.**
19ed0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
19ee0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ()]..*/.int sqli
19ef0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
19f00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
19f10 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
19f20 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
19f30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
19f40 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 , /* SQL to
19f50 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
19f60 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 char ***pazRes
19f70 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c ult, /* Resul
19f80 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
19f90 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c */. int *pnRow,
19fa0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
19fb0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
19fc0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
19fd0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c */. int *pnCol
19fe0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e umn, /* N
19ff0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1a000 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
1a010 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
1a020 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 *pzErrmsg
1a030 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
1a040 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
1a050 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
1a060 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 e_table(char **r
1a070 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 esult);../*.** C
1a080 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 API3REF: Formatt
1a090 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 ed String Printi
1a0a0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a ng Functions.**.
1a0b0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1a0c0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 s are work-alike
1a0d0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 s of the "printf
1a0e0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 ()" family of fu
1a0f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 nctions.** from
1a100 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
1a110 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ibrary..**.** ^T
1a120 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e he sqlite3_mprin
1a130 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 tf() and sqlite3
1a140 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _vmprintf() rout
1a150 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 ines write their
1a160 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f .** results into
1a170 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
1a180 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
1a190 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 alloc()]..** The
1a1a0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
1a1b0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 d by these two r
1a1c0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 outines should b
1a1d0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 e.** released by
1a1e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1a1f0 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e ]. ^Both routin
1a200 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e es return a.** N
1a210 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b ULL pointer if [
1a220 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1a230 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 ] is unable to a
1a240 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a llocate enough.*
1a250 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 * memory to hold
1a260 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 the resulting s
1a270 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 tring..**.** ^(T
1a280 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 he sqlite3_snpri
1a290 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ntf() routine is
1a2a0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 similar to "snp
1a2b0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a rintf()" from.**
1a2c0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
1a2d0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 library. The re
1a2e0 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 sult is written
1a2f0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 into the.** buff
1a300 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 er supplied as t
1a310 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1a320 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 ter whose size i
1a330 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 s given by.** th
1a340 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
1a350 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 r. Note that the
1a360 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a order of the.**
1a370 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d first two param
1a380 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 eters is reverse
1a390 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 d from snprintf(
1a3a0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e ).)^ This is an
1a3b0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 .** historical a
1a3c0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e ccident that can
1a3d0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 not be fixed wit
1a3e0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a hout breaking.**
1a3f0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
1a400 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 tibility. ^(Not
1a410 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 e also that sqli
1a420 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
1a430 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e * returns a poin
1a440 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 ter to its buffe
1a450 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
1a460 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 number of.** ch
1a470 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c aracters actuall
1a480 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 y written into t
1a490 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 he buffer.)^ We
1a4a0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 admit that.** t
1a4b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
1a4c0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 racters written
1a4d0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 would be a more
1a4e0 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a useful return.**
1a4f0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 value but we ca
1a500 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 nnot change the
1a510 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1a520 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e f sqlite3_snprin
1a530 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 tf().** now with
1a540 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d out breaking com
1a550 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
1a560 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 * ^As long as th
1a570 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 e buffer size is
1a580 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 greater than ze
1a590 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 ro, sqlite3_snpr
1a5a0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e intf().** guaran
1a5b0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 tees that the bu
1a5c0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a ffer is always z
1a5d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 ero-terminated.
1a5e0 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 ^The first.** p
1a5f0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 arameter "n" is
1a600 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f the total size o
1a610 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e f the buffer, in
1a620 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f cluding space fo
1a630 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 r.** the zero te
1a640 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 rminator. So th
1a650 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 e longest string
1a660 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d that can be com
1a670 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 pletely.** writt
1a680 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 en will be n-1 c
1a690 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
1a6a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 ^The sqlite3_vs
1a6b0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e nprintf() routin
1a6c0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 e is a varargs v
1a6d0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 ersion of sqlite
1a6e0 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 3_snprintf()..**
1a6f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1a700 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 es all implement
1a710 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c some additional
1a720 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f formatting.** o
1a730 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 ptions that are
1a740 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 useful for const
1a750 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 ructing SQL stat
1a760 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f ements..** All o
1a770 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e f the usual prin
1a780 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 tf() formatting
1a790 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 options apply.
1a7a0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 In addition, the
1a7b0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 re.** is are "%q
1a7c0 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a ", "%Q", and "%z
1a7d0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a " options..**.**
1a7e0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e ^(The %q option
1a7f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 works like %s i
1a800 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 n that it substi
1a810 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d tutes a nul-term
1a820 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
1a830 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 from the argume
1a840 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 nt list. But %q
1a850 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 also doubles ev
1a860 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 ery '\'' charact
1a870 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 er..** %q is des
1a880 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e igned for use in
1a890 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 side a string li
1a8a0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 teral.)^ By dou
1a8b0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a bling each '\''.
1a8c0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 ** character it
1a8d0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 escapes that cha
1a8e0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 racter and allow
1a8f0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 s it to be inser
1a900 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ted into.** the
1a910 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f string..**.** Fo
1a920 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d r example, assum
1a930 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 e the string var
1a940 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 iable zText cont
1a950 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c ains text as fol
1a960 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1a970 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1a980 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 char *zText =
1a990 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 "It's a happy da
1a9a0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!";.** </pre></
1a9b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1a9c0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 * One can use th
1a9d0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 is text in an SQ
1a9e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 L statement as f
1a9f0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1aa00 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1aa10 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
1aa20 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
1aa30 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
1aa40 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 ble VALUES('%q')
1aa50 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
1aa60 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
1aa70 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
1aa80 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
1aa90 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
1aaa0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1aab0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
1aac0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e %q format strin
1aad0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 g is used, the '
1aae0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e \'' character in
1aaf0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 zText.** is esc
1ab00 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c aped and the SQL
1ab10 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 generated is as
1ab20 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1ab30 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1ab40 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
1ab50 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
1ab60 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 'It''s a happy d
1ab70 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!').** </pre><
1ab80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1ab90 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 ** This is corre
1aba0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 ct. Had we used
1abb0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %s instead of %
1abc0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 q, the generated
1abd0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 SQL.** would ha
1abe0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 ve looked like t
1abf0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 his:.**.** <bloc
1ac00 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1ac10 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
1ac20 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 le1 VALUES('It's
1ac30 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b a happy day!');
1ac40 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1ac50 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1ac60 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c is second exampl
1ac70 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 e is an SQL synt
1ac80 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 ax error. As a
1ac90 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 general rule you
1aca0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 should.** alway
1acb0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 s use %q instead
1acc0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 of %s when inse
1acd0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 rting text into
1ace0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
1acf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 ..**.** ^(The %Q
1ad00 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1ad10 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 ke %q except it
1ad20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 also adds single
1ad30 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a quotes around.*
1ad40 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 * the outside of
1ad50 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e the total strin
1ad60 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 g. Additionally
1ad70 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 , if the paramet
1ad80 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 er in the.** arg
1ad90 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 ument list is a
1ada0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 NULL pointer, %Q
1adb0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 substitutes the
1adc0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 text "NULL" (wi
1add0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 thout.** single
1ade0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 quotes).)^ So,
1adf0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 for example, one
1ae00 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a could say:.**.*
1ae10 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1ae20 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
1ae30 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
1ae40 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
1ae50 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 O table VALUES(%
1ae60 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 Q)", zText);.**
1ae70 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1ae80 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1ae90 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1aea0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1aeb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1aec0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
1aed0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 above will rende
1aee0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 r a correct SQL
1aef0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
1af00 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c zSQL.** variabl
1af10 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 e even if the zT
1af20 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 ext variable is
1af30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
1af40 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 **.** ^(The "%z"
1af50 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1af60 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 on works like "%
1af70 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a s" but with the.
1af80 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 ** addition that
1af90 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e after the strin
1afa0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 g has been read
1afb0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a and copied into.
1afc0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b ** the result, [
1afd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1afe0 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 is called on the
1aff0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e input string.)^
1b000 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 .*/.char *sqlite
1b010 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 3_mprintf(const
1b020 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 char*,...);.char
1b030 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e *sqlite3_vmprin
1b040 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 tf(const char*,
1b050 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a va_list);.char *
1b060 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1b070 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
1b080 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 char*, ...);.ch
1b090 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 ar *sqlite3_vsnp
1b0a0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c rintf(int,char*,
1b0b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
1b0c0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 list);../*.** CA
1b0d0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
1b0e0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 llocation Subsys
1b0f0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 tem.**.** The SQ
1b100 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 Lite core uses t
1b110 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 hese three routi
1b120 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 nes for all of i
1b130 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e ts own.** intern
1b140 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 al memory alloca
1b150 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 tion needs. "Cor
1b160 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f e" in the previo
1b170 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 us sentence.** d
1b180 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 oes not include
1b190 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d operating-system
1b1a0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d specific VFS im
1b1b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 plementation. T
1b1c0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 he.** Windows VF
1b1d0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 S uses native ma
1b1e0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
1b1f0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 ) for some opera
1b200 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions..**.** ^Th
1b210 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
1b220 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
1b230 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1b240 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 a block.** of me
1b250 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 mory at least N
1b260 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c bytes in length,
1b270 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
1b280 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 parameter..** ^I
1b290 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
1b2a0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 () is unable to
1b2b0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e obtain sufficien
1b2c0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 t free.** memory
1b2d0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e , it returns a N
1b2e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 ULL pointer. ^I
1b2f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
1b300 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f N to.** sqlite3_
1b310 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f malloc() is zero
1b320 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 or negative the
1b330 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 n sqlite3_malloc
1b340 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 () returns.** a
1b350 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1b360 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
1b370 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 ite3_free() with
1b380 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 a pointer previ
1b390 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a ously returned.*
1b3a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c * by sqlite3_mal
1b3b0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 loc() or sqlite3
1b3c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 _realloc() relea
1b3d0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 ses that memory
1b3e0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 so.** that it mi
1b3f0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 ght be reused.
1b400 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 ^The sqlite3_fre
1b410 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a e() routine is.*
1b420 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 * a no-op if is
1b430 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
1b440 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 LL pointer. Pas
1b450 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e sing a NULL poin
1b460 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ter.** to sqlite
1b470 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 3_free() is harm
1b480 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 less. After bei
1b490 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 ng freed, memory
1b4a0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 .** should neith
1b4b0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 er be read nor w
1b4c0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 ritten. Even re
1b4d0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 ading previously
1b4e0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 freed.** memory
1b4f0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e might result in
1b500 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
1b510 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 fault or other s
1b520 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 evere error..**
1b530 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f Memory corruptio
1b540 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f n, a segmentatio
1b550 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 n fault, or othe
1b560 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a r severe error.*
1b570 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 * might result i
1b580 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 f sqlite3_free()
1b590 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
1b5a0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
1b5b0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e er that.** was n
1b5c0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ot obtained from
1b5d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1b5e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 ) or sqlite3_rea
1b5f0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 lloc()..**.** ^(
1b600 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c The sqlite3_real
1b610 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 loc() interface
1b620 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 attempts to resi
1b630 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 ze a.** prior me
1b640 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1b650 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e to be at least N
1b660 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 bytes, where N
1b670 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 is the.** second
1b680 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 parameter. The
1b690 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1b6a0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 on to be resized
1b6b0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a is the first.**
1b6c0 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 parameter.)^ ^
1b6d0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 If the first par
1b6e0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1b6f0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 3_realloc().** i
1b700 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1b710 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 then its behavi
1b720 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 or is identical
1b730 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 to calling.** sq
1b740 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 lite3_malloc(N)
1b750 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 where N is the s
1b760 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1b770 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1b780 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 oc()..** ^If the
1b790 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1b7a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
1b7b0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
1b7c0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
1b7d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
1b7e0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
1b7f0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
1b800 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 * sqlite3_free(P
1b810 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65 ) where P is the
1b820 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1b830 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
1b840 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 loc()..** ^sqlit
1b850 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 e3_realloc() ret
1b860 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1b870 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 o a memory alloc
1b880 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c ation.** of at l
1b890 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 east N bytes in
1b8a0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 size or NULL if
1b8b0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 sufficient memor
1b8c0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 y is unavailable
1b8d0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 ..** ^If M is th
1b8e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 e size of the pr
1b8f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 ior allocation,
1b900 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 then min(N,M) by
1b910 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 tes.** of the pr
1b920 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 ior allocation a
1b930 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 re copied into t
1b940 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
1b950 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a buffer returned.
1b960 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 ** by sqlite3_re
1b970 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 alloc() and the
1b980 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1b990 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 is freed..** ^I
1b9a0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f f sqlite3_reallo
1b9b0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c c() returns NULL
1b9c0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 , then the prior
1b9d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 allocation.** i
1b9e0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a s not freed..**.
1b9f0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 ** ^The memory r
1ba00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1ba10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 e3_malloc() and
1ba20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1ba30 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 ).** is always a
1ba40 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 ligned to at lea
1ba50 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 st an 8 byte bou
1ba60 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a ndary, or to a.*
1ba70 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 * 4 byte boundar
1ba80 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 y if the [SQLITE
1ba90 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f _4_BYTE_ALIGNED_
1baa0 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d MALLOC] compile-
1bab0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 time.** option i
1bac0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e s used..**.** In
1bad0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
1bae0 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 3.5.0 and 3.5.1,
1baf0 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 it was possible
1bb00 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 to define.** th
1bb10 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 e SQLITE_OMIT_ME
1bb20 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 MORY_ALLOCATION
1bb30 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 which would caus
1bb40 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a e the built-in.*
1bb50 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
1bb60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
1bb70 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 es to be omitted
1bb80 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 . That capabili
1bb90 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 ty.** is no long
1bba0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e er provided. On
1bbb0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f ly built-in memo
1bbc0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 ry allocators ca
1bbd0 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n be used..**.**
1bbe0 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 Prior to SQLite
1bbf0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c version 3.7.10,
1bc00 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 the Windows OS
1bc10 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 interface layer
1bc20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 called.** the sy
1bc30 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e stem malloc() an
1bc40 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c d free() directl
1bc50 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e y when convertin
1bc60 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 g.** filenames b
1bc70 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 etween the UTF-8
1bc80 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 encoding used b
1bc90 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 y SQLite.** and
1bca0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d whatever filenam
1bcb0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 e encoding is us
1bcc0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 ed by the partic
1bcd0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 ular Windows.**
1bce0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d installation. M
1bcf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1bd00 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 errors were det
1bd10 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 ected, but.** th
1bd20 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 ey were reported
1bd30 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 back as [SQLITE
1bd40 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a _CANTOPEN] or.**
1bd50 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 [SQLITE_IOERR]
1bd60 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c rather than [SQL
1bd70 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a ITE_NOMEM]..**.*
1bd80 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 * The pointer ar
1bd90 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 guments to [sqli
1bda0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 te3_free()] and
1bdb0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1bdc0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 ()].** must be e
1bdd0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c ither NULL or el
1bde0 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 se pointers obta
1bdf0 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f ined from a prio
1be00 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 r.** invocation
1be10 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c of [sqlite3_mall
1be20 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 oc()] or [sqlite
1be30 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 3_realloc()] tha
1be40 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 t have.** not ye
1be50 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e t been released.
1be60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
1be70 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
1be80 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e read or write an
1be90 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 y part of.** a b
1bea0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 lock of memory a
1beb0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
1bec0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a released using.
1bed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
1bee0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1bef0 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 realloc()]..*/.v
1bf00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c oid *sqlite3_mal
1bf10 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a loc(int);.void *
1bf20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1bf30 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 void*, int);.voi
1bf40 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 d sqlite3_free(v
1bf50 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1bf60 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
1bf70 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 llocator Statist
1bf80 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ics.**.** SQLite
1bf90 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
1bfa0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
1bfb0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
1bfc0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
1bfd0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
1bfe0 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
1bff0 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
1c000 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1c010 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
1c020 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
1c030 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
1c040 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
1c050 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tem..**.** ^The
1c060 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1c070 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 used()] routine
1c080 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
1c090 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f er of bytes.** o
1c0a0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 f memory current
1c0b0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 ly outstanding (
1c0c0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 malloced but not
1c0d0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 freed)..** ^The
1c0e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1c0f0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f _highwater()] ro
1c100 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
1c110 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c e maximum.** val
1c120 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d ue of [sqlite3_m
1c130 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 emory_used()] si
1c140 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 nce the high-wat
1c150 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c er mark.** was l
1c160 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 ast reset. ^The
1c170 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
1c180 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
1c190 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a ory_used()] and.
1c1a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1c1b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1c1c0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 include any over
1c1d0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 head.** added by
1c1e0 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 SQLite in its i
1c1f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1c200 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1c210 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 ()],.** but not
1c220 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 overhead added b
1c230 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c y the any underl
1c240 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 ying system libr
1c250 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ary.** routines
1c260 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 that [sqlite3_ma
1c270 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c lloc()] may call
1c280 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ..**.** ^The mem
1c290 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d ory high-water m
1c2a0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 ark is reset to
1c2b0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
1c2c0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 e of.** [sqlite3
1c2d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1c2e0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 if and only if t
1c2f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a he parameter to.
1c300 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1c310 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1c320 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 is true. ^The v
1c330 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a alue returned.**
1c340 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
1c350 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 ory_highwater(1)
1c360 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 ] is the high-wa
1c370 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f ter mark.** prio
1c380 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a r to the reset..
1c390 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
1c3a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
1c3b0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 used(void);.sqli
1c3c0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
1c3d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1c3e0 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 er(int resetFlag
1c3f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1c400 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f EF: Pseudo-Rando
1c410 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 m Number Generat
1c420 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 or.**.** SQLite
1c430 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d contains a high-
1c440 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 quality pseudo-r
1c450 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e andom number gen
1c460 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 erator (PRNG) us
1c470 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 ed to.** select
1c480 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 random [ROWID |
1c490 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 ROWIDs] when ins
1c4a0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 erting new recor
1c4b0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 ds into a table
1c4c0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 that.** already
1c4d0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 uses the largest
1c4e0 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 possible [ROWID
1c4f0 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 ]. The PRNG is
1c500 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a also used for.**
1c510 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 the build-in ra
1c520 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f ndom() and rando
1c530 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 mblob() SQL func
1c540 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 tions. This int
1c550 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a erface allows.**
1c560 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f applications to
1c570 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 access the same
1c580 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 PRNG for other
1c590 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 purposes..**.**
1c5a0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 ^A call to this
1c5b0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e routine stores N
1c5c0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
1c5d0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 ness into buffer
1c5e0 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 P..**.** ^The f
1c5f0 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 irst time this r
1c600 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 outine is invoke
1c610 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e d (either intern
1c620 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 ally or by.** th
1c630 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 e application) t
1c640 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 he PRNG is seede
1c650 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 d using randomne
1c660 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ss obtained.** f
1c670 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e rom the xRandomn
1c680 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ess method of th
1c690 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
1c6a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a e3_vfs] object..
1c6b0 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 ** ^On all subse
1c6c0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e quent invocation
1c6d0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 s, the pseudo-ra
1c6e0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 ndomness is gene
1c6f0 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 rated.** interna
1c700 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 lly and without
1c710 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 recourse to the
1c720 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 [sqlite3_vfs] xR
1c730 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 andomness.** met
1c740 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c hod..*/.void sql
1c750 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 ite3_randomness(
1c760 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b int N, void *P);
1c770 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c780 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 : Compile-Time A
1c790 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c uthorization Cal
1c7a0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 lbacks.**.** ^Th
1c7b0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 is routine regis
1c7c0 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a ters an authoriz
1c7d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 er callback with
1c7e0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a a particular.**
1c7f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1c800 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 ction], supplied
1c810 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
1c820 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
1c830 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1c840 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 ack is invoked a
1c850 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 s SQL statements
1c860 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 are being compi
1c870 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 led.** by [sqlit
1c880 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
1c890 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 its variants [s
1c8a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1c8b0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 2()],.** [sqlite
1c8c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 3_prepare16()] a
1c8d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
1c8e0 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 are16_v2()]. ^A
1c8f0 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 t various.** poi
1c900 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 nts during the c
1c910 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 ompilation proce
1c920 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 ss, as logic is
1c930 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a being created.**
1c940 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 to perform vari
1c950 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 ous actions, the
1c960 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1c970 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
1c980 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f to.** see if tho
1c990 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 se actions are a
1c9a0 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 llowed. ^The au
1c9b0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1c9c0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 k should.** retu
1c9d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 rn [SQLITE_OK] t
1c9e0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 o allow the acti
1c9f0 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f on, [SQLITE_IGNO
1ca00 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 RE] to disallow
1ca10 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 the.** specific
1ca20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 action but allow
1ca30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1ca40 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 nt to continue t
1ca50 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 o be.** compiled
1ca60 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
1ca70 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 Y] to cause the
1ca80 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 entire SQL state
1ca90 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 ment to be.** re
1caa0 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 jected with an e
1cab0 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 rror. ^If the a
1cac0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1cad0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e ck returns.** an
1cae0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 y value other th
1caf0 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 an [SQLITE_IGNOR
1cb00 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c E], [SQLITE_OK],
1cb10 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 or [SQLITE_DENY
1cb20 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 ].** then the [s
1cb30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1cb40 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 2()] or equivale
1cb50 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 nt call that tri
1cb60 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 ggered.** the au
1cb70 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 thorizer will fa
1cb80 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 il with an error
1cb90 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 message..**.**
1cba0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
1cbb0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
1cbc0 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e E_OK], that mean
1cbd0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a s the operation.
1cbe0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 ** requested is
1cbf0 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 ok. ^When the c
1cc00 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1cc10 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 [SQLITE_DENY], t
1cc20 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 he.** [sqlite3_p
1cc30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
1cc40 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 equivalent call
1cc50 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
1cc60 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 he.** authorizer
1cc70 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 will fail with
1cc80 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 an error message
1cc90 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 explaining that
1cca0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 .** access is de
1ccb0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 nied. .**.** ^Th
1ccc0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
1ccd0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 r to the authori
1cce0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 zer callback is
1ccf0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 a copy of the th
1cd00 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
1cd10 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
1cd20 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 set_authorizer()
1cd30 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 interface. ^The
1cd40 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1cd50 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c r.** to the call
1cd60 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
1cd70 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 er [SQLITE_COPY
1cd80 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 | action code] t
1cd90 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a hat specifies.**
1cda0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 the particular
1cdb0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
1cdc0 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 horized. ^The th
1cdd0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 ird through sixt
1cde0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 h parameters.**
1cdf0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1ce00 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 are zero-termina
1ce10 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
1ce20 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f contain additio
1ce30 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 nal.** details a
1ce40 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 bout the action
1ce50 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 to be authorized
1ce60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
1ce70 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
1ce80 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
1ce90 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
1cea0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
1ceb0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
1cec0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
1ced0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
1cee0 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
1cef0 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
1cf00 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
1cf10 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
1cf20 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
1cf30 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
1cf40 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
1cf50 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
1cf60 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
1cf70 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
1cf80 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
1cf90 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
1cfa0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
1cfb0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
1cfc0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
1cfd0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
1cfe0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 ^If the action
1cff0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f code is [SQLITE_
1d000 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 DELETE] and the
1d010 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1d020 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f .** [SQLITE_IGNO
1d030 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 RE] then the [DE
1d040 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 LETE] operation
1d050 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 proceeds but the
1d060 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 .** [truncate op
1d070 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 timization] is d
1d080 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 isabled and all
1d090 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 rows are deleted
1d0a0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a individually..*
1d0b0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a *.** An authoriz
1d0c0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 er is used when
1d0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1d0e0 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a | preparing].**
1d0f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1d100 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 from an untruste
1d110 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 d source, to ens
1d120 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ure that the SQL
1d130 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 statements.** d
1d140 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 o not try to acc
1d150 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72 ess data they ar
1d160 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f e not allowed to
1d170 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 see, or that th
1d180 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 ey do not.** try
1d190 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 to execute mali
1d1a0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 cious statements
1d1b0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 that damage the
1d1c0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a database. For.
1d1d0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 ** example, an a
1d1e0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 pplication may a
1d1f0 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 llow a user to e
1d200 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a nter arbitrary.*
1d210 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f * SQL queries fo
1d220 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 r evaluation by
1d230 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 a database. But
1d240 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1d250 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e does.** not wan
1d260 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 t the user to be
1d270 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 able to make ar
1d280 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 bitrary changes
1d290 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 to the.** databa
1d2a0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a se. An authoriz
1d2b0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 er could then be
1d2c0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 put in place wh
1d2d0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d ile the.** user-
1d2e0 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 entered SQL is b
1d2f0 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 eing [sqlite3_pr
1d300 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 epare | prepared
1d310 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c ] that.** disall
1d320 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 ows everything e
1d330 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 xcept [SELECT] s
1d340 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
1d350 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
1d360 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 at need to proce
1d370 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 ss SQL from untr
1d380 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a usted sources.**
1d390 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 might also cons
1d3a0 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 ider lowering re
1d3b0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 source limits us
1d3c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d ing [sqlite3_lim
1d3d0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d it()].** and lim
1d3e0 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 iting database s
1d3f0 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d ize using the [m
1d400 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b ax_page_count] [
1d410 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 PRAGMA].** in ad
1d420 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 dition to using
1d430 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a an authorizer..*
1d440 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 *.** ^(Only a si
1d450 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ngle authorizer
1d460 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 can be in place
1d470 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f on a database co
1d480 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 nnection.** at a
1d490 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c time. Each cal
1d4a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 l to sqlite3_set
1d4b0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 _authorizer over
1d4c0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 rides the.** pre
1d4d0 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e vious call.)^ ^
1d4e0 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 Disable the auth
1d4f0 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c orizer by instal
1d500 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c ling a NULL call
1d510 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 back..** The aut
1d520 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 horizer is disab
1d530 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
1d540 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 **.** The author
1d550 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 izer callback mu
1d560 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
1d570 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
1d580 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
1d590 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
1d5a0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1d5b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1d5c0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ack..** Note tha
1d5d0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
1d5e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
1d5f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
1d600 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
1d610 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
1d620 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
1d630 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
1d640 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
1d650 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 graph..**.** ^Wh
1d660 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 en [sqlite3_prep
1d670 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 are_v2()] is use
1d680 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 d to prepare a s
1d690 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a tatement, the.**
1d6a0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 statement might
1d6b0 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 be re-prepared
1d6c0 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f during [sqlite3_
1d6d0 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 step()] due to a
1d6e0 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e .** schema chan
1d6f0 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 ge. Hence, the
1d700 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
1d710 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 ld ensure that t
1d720 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 he.** correct au
1d730 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1d740 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 k remains in pla
1d750 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 ce during the [s
1d760 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
1d770 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 **.** ^Note that
1d780 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1d790 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
1d7a0 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a ked only during.
1d7b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1d7c0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 are()] or its va
1d7d0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 riants. Authori
1d7e0 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a zation is not.**
1d7f0 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e performed durin
1d800 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c g statement eval
1d810 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 uation in [sqlit
1d820 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 e3_step()], unle
1d830 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 ss.** as stated
1d840 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
1d850 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 paragraph, sqlit
1d860 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 e3_step() invoke
1d870 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 s.** sqlite3_pre
1d880 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 pare_v2() to rep
1d890 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 repare a stateme
1d8a0 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d nt after a schem
1d8b0 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 a change..*/.int
1d8c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
1d8d0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 horizer(. sqlit
1d8e0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 e3*,. int (*xAu
1d8f0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f th)(void*,int,co
1d900 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
1d910 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1d920 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a *,const char*),.
1d930 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 void *pUserDat
1d940 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 a.);../*.** CAPI
1d950 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
1d960 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a Return Codes.**
1d970 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1d980 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1d990 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
1d9a0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 lback function]
1d9b0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 must.** return e
1d9c0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b ither [SQLITE_OK
1d9d0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 ] or one of thes
1d9e0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 e two constants
1d9f0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 in order.** to s
1da00 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 ignal SQLite whe
1da10 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
1da20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 action is permit
1da30 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ted. See the.**
1da40 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
1da50 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
1da60 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 rizer documentat
1da70 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f ion] for additio
1da80 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
1da90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 on..**.** Note t
1daa0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 hat SQLITE_IGNOR
1dab0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 E is also used a
1dac0 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c s a [SQLITE_ROLL
1dad0 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f BACK | return co
1dae0 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 de].** from the
1daf0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e [sqlite3_vtab_on
1db00 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 _conflict()] int
1db10 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 erface..*/.#defi
1db20 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 ne SQLITE_DENY
1db30 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 1 /* Abort th
1db40 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
1db50 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f with an error */
1db60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1db70 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f IGNORE 2 /* Do
1db80 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 n't allow access
1db90 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 , but don't gene
1dba0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f rate an error */
1dbb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1dbc0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 : Authorizer Act
1dbd0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ion Codes.**.**
1dbe0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
1dbf0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
1dc00 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
1dc10 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
1dc20 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
1dc30 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
1dc40 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 horize certain S
1dc50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 QL statement act
1dc60 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ions. The.** se
1dc70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
1dc80 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
1dc90 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
1dca0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 e that specifies
1dcb0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 .** what action
1dcc0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 is being authori
1dcd0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 zed. These are
1dce0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 the integer acti
1dcf0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a on codes that.**
1dd00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1dd10 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 callback may be
1dd20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 passed..**.** Th
1dd30 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 ese action code
1dd40 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 values signify w
1dd50 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 hat kind of oper
1dd60 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a ation is to be.*
1dd70 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 * authorized. T
1dd80 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 he 3rd and 4th p
1dd90 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 arameters to the
1dda0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a authorization.*
1ddb0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
1ddc0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 ion will be para
1ddd0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 meters or NULL d
1dde0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
1ddf0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f h of these.** co
1de00 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 des is used as t
1de10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1de20 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 ter. ^(The 5th
1de30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1de40 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
1de50 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
1de60 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
1de70 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
1de80 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 mp",.** etc.) if
1de90 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 applicable.)^
1dea0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 ^The 6th paramet
1deb0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
1dec0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a izer callback.**
1ded0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
1dee0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 the inner-most t
1def0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 rigger or view t
1df00 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 hat is responsib
1df10 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 le for.** the ac
1df20 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 cess attempt or
1df30 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 NULL if this acc
1df40 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 ess attempt is d
1df50 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 irectly from.**
1df60 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f top-level SQL co
1df70 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a de..*/./********
1df80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1df90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1dfa0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a *** 3rd ********
1dfb0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a **** 4th *******
1dfc0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ****/.#define SQ
1dfd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 LITE_CREATE_INDE
1dfe0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f X 1 /
1dff0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1e000 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1e010 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e020 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 ITE_CREATE_TABLE
1e030 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 2 /*
1e040 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1e050 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1e060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e070 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 TE_CREATE_TEMP_I
1e080 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 NDEX 3 /*
1e090 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
1e0a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1e0b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e0c0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 E_CREATE_TEMP_TA
1e0d0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 BLE 4 /* T
1e0e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1e0f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1e100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e110 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 _CREATE_TEMP_TRI
1e120 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 GGER 5 /* Tr
1e130 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
1e140 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1e150 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e160 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 CREATE_TEMP_VIEW
1e170 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 6 /* Vie
1e180 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
1e190 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1e1a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1e1b0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 REATE_TRIGGER
1e1c0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 7 /* Trig
1e1d0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
1e1e0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1e1f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1e200 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 EATE_VIEW
1e210 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 8 /* View
1e220 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1e230 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1e240 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c efine SQLITE_DEL
1e250 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ETE
1e260 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 9 /* Table
1e270 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1e280 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1e290 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1e2a0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
1e2b0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 10 /* Index N
1e2c0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
1e2d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1e2e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1e2f0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
1e300 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 11 /* Table Na
1e310 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1e320 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1e330 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1e340 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 EMP_INDEX 1
1e350 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 2 /* Index Nam
1e360 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
1e370 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1e380 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
1e390 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 MP_TABLE 13
1e3a0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1e3b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1e3c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1e3d0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
1e3e0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 P_TRIGGER 14
1e3f0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
1e400 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
1e410 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e420 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
1e430 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 _VIEW 15
1e440 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
1e450 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1e460 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1e470 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 QLITE_DROP_TRIGG
1e480 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 ER 16
1e490 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
1e4a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1e4b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e4c0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 LITE_DROP_VIEW
1e4d0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 17 /
1e4e0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
1e4f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1e500 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e510 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 ITE_INSERT
1e520 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 18 /*
1e530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1e540 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1e550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e560 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 TE_PRAGMA
1e570 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 19 /*
1e580 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 Pragma Name
1e590 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 1st arg or NULL
1e5a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e5b0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 E_READ
1e5c0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 20 /* T
1e5d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
1e5e0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
1e5f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e600 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
1e610 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 21 /* NU
1e620 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
1e630 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1e640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e650 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 TRANSACTION
1e660 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 22 /* Ope
1e670 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c ration NUL
1e680 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1e690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
1e6a0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 PDATE
1e6b0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 23 /* Tabl
1e6c0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
1e6d0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
1e6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 define SQLITE_AT
1e6f0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
1e700 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 24 /* Filen
1e710 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 ame NULL
1e720 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1e730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 efine SQLITE_DET
1e740 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
1e750 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 25 /* Databa
1e760 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 se Name NULL
1e770 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1e780 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 fine SQLITE_ALTE
1e790 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 R_TABLE
1e7a0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 26 /* Databas
1e7b0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e e Name Table N
1e7c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1e7d0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 ine SQLITE_REIND
1e7e0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EX
1e7f0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 27 /* Index Na
1e800 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1e810 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1e820 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a ne SQLITE_ANALYZ
1e830 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 E 2
1e840 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
1e850 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1e860 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1e870 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1e880 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 VTABLE 29
1e890 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1e8a0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
1e8b0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
1e8c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 SQLITE_DROP_VTA
1e8d0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 BLE 30
1e8e0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1e8f0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
1e900 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e910 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 SQLITE_FUNCTION
1e920 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 31
1e930 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
1e940 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d Function Nam
1e950 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 e */.#define S
1e960 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 QLITE_SAVEPOINT
1e970 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 32
1e980 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
1e990 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d Savepoint Nam
1e9a0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e */.#define SQ
1e9b0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
1e9c0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
1e9d0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 * No longer used
1e9e0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
1e9f0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
1ea00 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
1ea10 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
1ea20 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
1ea30 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1ea40 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
1ea50 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
1ea60 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
1ea70 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
1ea80 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
1ea90 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
1eaa0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1eab0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
1eac0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
1ead0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
1eae0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
1eaf0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
1eb00 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
1eb10 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
1eb20 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 ep()]..** ^The s
1eb30 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
1eb40 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1eb50 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 ed with a UTF-8
1eb60 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
1eb70 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
1eb80 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 t text as the st
1eb90 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
1eba0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a gins executing..
1ebb0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 ** ^(Additional
1ebc0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
1ebd0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 callbacks might
1ebe0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
1ebf0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
1ec00 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
1ec10 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
1ec20 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
1ec30 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
1ec40 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
1ec50 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
1ec60 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a trigger.)^.**.*
1ec70 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 * The [SQLITE_TR
1ec80 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 ACE_SIZE_LIMIT]
1ec90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
1eca0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
1ecb0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 to limit.** the
1ecc0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 length of [bound
1ecd0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 parameter] expa
1ece0 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 nsion in the out
1ecf0 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 put of sqlite3_t
1ed00 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 race()..**.** ^T
1ed10 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
1ed20 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
1ed30 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
1ed40 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
1ed50 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
1ed60 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
1ed70 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 s. ^The profile
1ed80 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
1ed90 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e ns.** the origin
1eda0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 al statement tex
1edb0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 t and an estimat
1edc0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 e of wall-clock
1edd0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c time.** of how l
1ede0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 ong that stateme
1edf0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 nt took to run.
1ee00 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 ^The profile ca
1ee10 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 llback.** time i
1ee20 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 s in units of na
1ee30 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 noseconds, howev
1ee40 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 er the current i
1ee50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
1ee60 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 is only capable
1ee70 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 of millisecond
1ee80 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 resolution so th
1ee90 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e e six least sign
1eea0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 ificant.** digit
1eeb0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 s in the time ar
1eec0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 e meaningless.
1eed0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
1eee0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 of SQLite.** mig
1eef0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 ht provide great
1ef00 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e er resolution on
1ef10 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 the profiler ca
1ef20 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 llback. The.**
1ef30 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
1ef40 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f ) function is co
1ef50 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d nsidered experim
1ef60 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 ental and is.**
1ef70 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
1ef80 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 e in future vers
1ef90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
1efa0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
1efb0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
1efc0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
1efd0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
1efe0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
1eff0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 E_EXPERIMENTAL v
1f000 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f oid *sqlite3_pro
1f010 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
1f020 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
1f030 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
1f040 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
1f050 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
1f060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
1f070 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
1f080 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 lbacks.**.** ^Th
1f090 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 e sqlite3_progre
1f0a0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 ss_handler(D,N,X
1f0b0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 ,P) interface ca
1f0c0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 uses the callbac
1f0d0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 k.** function X
1f0e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 to be invoked pe
1f0f0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e riodically durin
1f100 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 g long running c
1f110 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
1f120 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 te3_exec()], [sq
1f130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e lite3_step()] an
1f140 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 d [sqlite3_get_t
1f150 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 able()] for.** d
1f160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f170 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c on D. An exampl
1f180 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a e use for this.*
1f190 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
1f1a0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 o keep a GUI upd
1f1b0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 ated during a la
1f1c0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a rge query..**.**
1f1d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
1f1e0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f P is passed thro
1f1f0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ugh as the only
1f200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1f210 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 .** callback fu
1f220 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 nction X. ^The
1f230 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 parameter N is t
1f240 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a he number of .**
1f250 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e [virtual machin
1f260 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 e instructions]
1f270 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 that are evaluat
1f280 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 ed between succe
1f290 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 ssive.** invocat
1f2a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c ions of the call
1f2b0 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f back X..**.** ^O
1f2c0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f nly a single pro
1f2d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 gress handler ma
1f2e0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 y be defined at
1f2f0 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 one time per.**
1f300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1f310 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 tion]; setting a
1f320 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 new progress ha
1f330 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 ndler cancels th
1f340 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e e.** old one. ^
1f350 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 Setting paramete
1f360 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 r X to NULL disa
1f370 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 bles the progres
1f380 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 s handler..** ^T
1f390 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
1f3a0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 ler is also disa
1f3b0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 bled by setting
1f3c0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 N to a value les
1f3d0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a s.** than 1..**.
1f3e0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 ** ^If the progr
1f3f0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 ess callback ret
1f400 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
1f410 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a he operation is.
1f420 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 ** interrupted.
1f430 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 This feature ca
1f440 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 n be used to imp
1f450 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e lement a.** "Can
1f460 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 cel" button on a
1f470 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 GUI progress di
1f480 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 alog box..**.**
1f490 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
1f4a0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 dler callback mu
1f4b0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 st not do anythi
1f4c0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 ng that will mod
1f4d0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 ify.** the datab
1f4e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
1f4f0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1f500 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
1f510 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
1f520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1f530 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
1f540 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
1f550 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
1f560 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f570 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
1f580 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
1f590 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
1f5a0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 ph..**.*/.void s
1f5b0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f qlite3_progress_
1f5c0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
1f5d0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f , int, int(*)(vo
1f5e0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f id*), void*);../
1f5f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
1f600 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 pening A New Dat
1f610 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
1f620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
1f630 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 utines open an S
1f640 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 QLite database f
1f650 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64 ile as specified
1f660 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 by the .** file
1f670 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e name argument. ^
1f680 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 The filename arg
1f690 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 ument is interpr
1f6a0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f eted as UTF-8 fo
1f6b0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 r.** sqlite3_ope
1f6c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
1f6d0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 open_v2() and as
1f6e0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
1f6f0 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 ative byte.** or
1f700 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f der for sqlite3_
1f710 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 open16(). ^(A [d
1f720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f730 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 on] handle is us
1f740 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 ually.** returne
1f750 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e d in *ppDb, even
1f760 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 if an error occ
1f770 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 urs. The only e
1f780 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 xception is that
1f790 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 .** if SQLite is
1f7a0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
1f7b0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f ate memory to ho
1f7c0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d ld the [sqlite3]
1f7d0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 object,.** a NU
1f7e0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 LL will be writt
1f7f0 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e en into *ppDb in
1f800 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 stead of a point
1f810 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 er to the [sqlit
1f820 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e e3].** object.)^
1f830 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61 ^(If the databa
1f840 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e se is opened (an
1f850 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 d/or created) su
1f860 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e ccessfully, then
1f870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 .** [SQLITE_OK]
1f880 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 is returned. Ot
1f890 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f herwise an [erro
1f8a0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 r code] is retur
1f8b0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b ned.)^ ^The.** [
1f8c0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
1f8d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 ] or [sqlite3_er
1f8e0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e rmsg16()] routin
1f8f0 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 es can be used t
1f900 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 o obtain.** an E
1f910 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 nglish language
1f920 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 description of t
1f930 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 he error followi
1f940 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 ng a failure of
1f950 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 any.** of the sq
1f960 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 lite3_open() rou
1f970 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tines..**.** ^Th
1f980 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 e default encodi
1f990 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 ng for the datab
1f9a0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ase will be UTF-
1f9b0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 8 if.** sqlite3_
1f9c0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
1f9d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63 3_open_v2() is c
1f9e0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46 alled and.** UTF
1f9f0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 -16 in the nativ
1fa00 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20 e byte order if
1fa10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
1fa20 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
1fa30 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
1fa40 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
1fa50 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
1fa60 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
1fa70 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
1fa80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
1fa90 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
1faa0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
1fab0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
1fac0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
1fad0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
1fae0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
1faf0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
1fb00 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
1fb10 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
1fb20 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
1fb30 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
1fb40 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
1fb50 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
1fb60 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
1fb70 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
1fb80 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
1fb90 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
1fba0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 ection. ^(The f
1fbb0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
1fbc0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
1fbd0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 n_v2() can take
1fbe0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
1fbf0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
1fc00 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
1fc10 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
1fc20 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
1fc30 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
1fc40 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
1fc50 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
1fc60 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
1fc70 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ,.** [SQLITE_OPE
1fc80 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c N_PRIVATECACHE],
1fc90 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
1fca0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a OPEN_URI] flags:
1fcb0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a )^.**.** <dl>.**
1fcc0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
1fcd0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 PEN_READONLY]</d
1fce0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
1fcf0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1fd00 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f in read-only mo
1fd10 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 de. If the data
1fd20 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
1fd30 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
1fd40 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
1fd50 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
1fd60 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
1fd70 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
1fd80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
1fd90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
1fda0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
1fdb0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 and writing if p
1fdc0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 ossible, or read
1fdd0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 ing.** only if t
1fde0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 he file is write
1fdf0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 protected by th
1fe00 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
1fe10 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a em. In either.*
1fe20 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 * case the datab
1fe30 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 ase must already
1fe40 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 exist, otherwis
1fe50 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 e an error is re
1fe60 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
1fe70 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
1fe80 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
1fe90 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 E] | [SQLITE_OPE
1fea0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a N_CREATE]</dt>.*
1feb0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
1fec0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
1fed0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
1fee0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 ting, and is cre
1fef0 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f ated if.** it do
1ff00 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
1ff10 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
1ff20 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
1ff30 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
1ff40 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
1ff50 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
1ff60 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 _open16().</dd>)
1ff70 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a ^.** </dl>.**.**
1ff80 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
1ff90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1ffa0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
1ffb0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
1ffc0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
1ffd0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 wn above optiona
1ffe0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
1fff0 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 h other.** [SQLI
20000 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
20010 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a | SQLITE_OPEN_*
20020 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 bits].** then t
20030 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
20040 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
20050 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
20060 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
20070 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
20080 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
20090 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
200a0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
200b0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
200c0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
200d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
200e0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
200f0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
20100 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
20110 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 tart-time. ^If
20120 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
20130 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
20140 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
20150 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
20160 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
20170 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
20180 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
20190 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
201a0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
201b0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
201c0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
201d0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
201e0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 e..** ^The [SQLI
201f0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
20200 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
20210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
20220 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
20230 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
20240 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
20250 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
20260 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
20270 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
20280 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
20290 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
202a0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
202b0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b e()]. ^The.** [
202c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
202d0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
202e0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
202f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
20300 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
20310 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
20320 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
20330 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
20340 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
20350 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
20360 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
20370 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
20380 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
20390 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
203a0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
203b0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
203c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
203d0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
203e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
203f0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
20400 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
20410 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
20420 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
20430 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
20440 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
20450 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s used..**.** ^I
20460 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
20470 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 s ":memory:", th
20480 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
20490 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 mporary in-memor
204a0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 y database.** is
204b0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
204c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 connection. ^T
204d0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 his in-memory da
204e0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 tabase will vani
204f0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 sh when.** the d
20500 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20510 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
20520 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
20530 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
20540 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 * make use of ad
20550 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c ditional special
20560 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 filenames that
20570 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 begin with the "
20580 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a :" character..**
20590 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
205a0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 ed that when a d
205b0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
205c0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 actually does b
205d0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 egin with.** a "
205e0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 :" character you
205f0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 should prefix t
20600 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 he filename with
20610 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 a pathname such
20620 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 as.** "./" to a
20630 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a void ambiguity..
20640 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
20650 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
20660 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
20670 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
20680 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 rary.** on-disk
20690 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
206a0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 created. ^This
206b0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 private databas
206c0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 e will be.** aut
206d0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
206e0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
206f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
20700 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
20710 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c .**.** [[URI fil
20720 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 enames in sqlite
20730 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 3_open()]] <h3>U
20740 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 RI Filenames</h3
20750 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 >.**.** ^If [URI
20760 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 filename] inter
20770 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
20780 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 bled, and the fi
20790 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
207a0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 ** begins with "
207b0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 file:", then the
207c0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 filename is int
207d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 erpreted as a UR
207e0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e I. ^URI.** filen
207f0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
20800 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 on is enabled if
20810 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
20820 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a N_URI] flag is.*
20830 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 * set in the fou
20840 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
20850 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
20860 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a ), or if it has.
20870 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 ** been enabled
20880 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 globally using t
20890 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
208a0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 G_URI] option wi
208b0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 th the.** [sqlit
208c0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 e3_config()] met
208d0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 hod or by the [S
208e0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 QLITE_USE_URI] c
208f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
20900 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c on..** As of SQL
20910 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
20920 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 7, URI filename
20930 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
20940 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 s turned off.**
20950 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 by default, but
20960 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
20970 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 of SQLite might
20980 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e enable URI filen
20990 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ame.** interpret
209a0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 ation by default
209b0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c . See "[URI fil
209c0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 enames]" for add
209d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
209e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 mation..**.** UR
209f0 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 I filenames are
20a00 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 parsed according
20a10 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 to RFC 3986. ^I
20a20 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 f the URI contai
20a30 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 ns an.** authori
20a40 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 ty, then it must
20a50 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d be either an em
20a60 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 pty string or th
20a70 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f e string .** "lo
20a80 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 calhost". ^If th
20a90 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e e authority is n
20aa0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 ot an empty stri
20ab0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 ng or "localhost
20ac0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 ", an .** error
20ad0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 is returned to t
20ae0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 he caller. ^The
20af0 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 fragment compone
20b00 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 nt of a URI, if
20b10 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 .** present, is
20b20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
20b30 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
20b40 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f path component o
20b50 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 f the URI as the
20b60 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 name of the dis
20b70 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 k file.** which
20b80 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 contains the dat
20b90 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 abase. ^If the p
20ba0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 ath begins with
20bb0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c a '/' character,
20bc0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 .** then it is
20bd0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
20be0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e n absolute path.
20bf0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f ^If the path do
20c00 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a es not begin .**
20c10 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 with a '/' (mea
20c20 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 ning that the au
20c30 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 thority section
20c40 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
20c50 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e the URI).** then
20c60 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 the path is int
20c70 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 erpreted as a re
20c80 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a lative path. .**
20c90 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 ^On windows, th
20ca0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e e first componen
20cb0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 t of an absolute
20cc0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 path .** is a d
20cd0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 rive specificati
20ce0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a on (e.g. "C:")..
20cf0 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 **.** [[core URI
20d00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
20d10 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 s]].** The query
20d20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
20d30 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 URI may contain
20d40 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
20d50 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a are interpreted.
20d60 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c ** either by SQL
20d70 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 ite itself, or b
20d80 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f y a [VFS | custo
20d90 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 m VFS implementa
20da0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 tion]..** SQLite
20db0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 interprets the
20dc0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
20dd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
20de0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
20df0 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 <li> <b>vfs</b
20e00 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 >: ^The "vfs" pa
20e10 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 rameter may be u
20e20 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 sed to specify t
20e30 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 he name of.**
20e40 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 a VFS object t
20e50 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 hat provides the
20e60 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
20e70 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
20e80 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 should.** b
20e90 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 e used to access
20ea0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
20eb0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 le on disk. ^If
20ec0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 this option is s
20ed0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 et to.** an
20ee0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 empty string the
20ef0 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a default VFS obj
20f00 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 ect is used. ^Sp
20f10 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
20f20 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 own.** VFS i
20f30 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 s an error. ^If
20f40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
20f50 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
20f60 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a e vfs option is.
20f70 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 ** present,
20f80 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 then the VFS spe
20f90 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 cified by the op
20fa0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 tion takes prece
20fb0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 dence over.**
20fc0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 the value pass
20fd0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 ed as the fourth
20fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
20ff0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
21000 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 .**.** <li> <b
21010 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 >mode</b>: ^(The
21020 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
21030 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 may be set to ei
21040 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c ther "ro", "rw",
21050 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f .** "rwc", o
21060 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 r "memory". Atte
21070 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 mpting to set it
21080 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 to any other va
21090 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e lue is.** an
210a0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 error)^. .**
210b0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 ^If "ro" is sp
210c0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 ecified, then th
210d0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
210e0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e ened for read-on
210f0 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 ly .** acces
21100 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 s, just as if th
21110 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
21120 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 EADONLY] flag ha
21130 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 d been set in th
21140 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 e .** third
21150 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
21160 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e te3_open_v2(). ^
21170 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 If the mode opti
21180 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a on is set to .**
21190 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 "rw", then
211a0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
211b0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d opened for read-
211c0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 write (but not c
211d0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 reate) .** a
211e0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c ccess, as if SQL
211f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
21200 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 TE (but not SQLI
21210 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 TE_OPEN_CREATE)
21220 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e had .** been
21230 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 set. ^Value "rw
21240 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 c" is equivalent
21250 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 to setting both
21260 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f .** SQLITE_
21270 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 OPEN_READWRITE a
21280 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 nd SQLITE_OPEN_C
21290 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 REATE. ^If the
212a0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a mode option is.*
212b0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 * set to "me
212c0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 mory" then a pur
212d0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 e [in-memory dat
212e0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 abase] that neve
212f0 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f r reads.** o
21300 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 r writes from di
21310 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 sk is used. ^It
21320 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 is an error to s
21330 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 pecify a value f
21340 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f or.** the mo
21350 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 de parameter tha
21360 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 t is less restri
21370 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 ctive than that
21380 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 specified by.**
21390 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 the flags pa
213a0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 ssed in the thir
213b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
213c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
213d0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c ..**.** <li> <
213e0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 b>cache</b>: ^Th
213f0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 e cache paramete
21400 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
21410 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 either "shared"
21420 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 or.** "priva
21430 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 te". ^Setting it
21440 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 to "shared" is
21450 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
21460 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 tting the.**
21470 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
21480 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 REDCACHE bit in
21490 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
214a0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 nt passed to.**
214b0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e sqlite3_open
214c0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 _v2(). ^Setting
214d0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 the cache parame
214e0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 ter to "private"
214f0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 is .** equi
21500 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
21510 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 g the SQLITE_OPE
21520 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 N_PRIVATECACHE b
21530 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 it..** ^If s
21540 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
21550 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 is used and the
21560 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 "cache" paramet
21570 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e er is present in
21580 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 .** a URI fi
21590 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 lename, its valu
215a0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 e overrides any
215b0 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 behavior request
215c0 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a ed by setting.**
215d0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
215e0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 _PRIVATECACHE or
215f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 SQLITE_OPEN_SHA
21600 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a REDCACHE flag..*
21610 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 * </ul>.**.** ^S
21620 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
21630 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 nown parameter i
21640 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 n the query comp
21650 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 onent of a URI i
21660 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f s not an.** erro
21670 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 r. Future versi
21680 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
21690 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 ght understand a
216a0 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a dditional query.
216b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ** parameters.
216c0 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 See "[query para
216d0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 meters with spec
216e0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 ial meaning to S
216f0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 QLite]" for.** a
21700 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
21710 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 ation..**.** [[U
21720 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
21730 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 ples]] <h3>URI f
21740 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 ilename examples
21750 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 </h3>.**.** <tab
21760 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c le border="1" al
21770 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 ign=center cellp
21780 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 adding=5>.** <tr
21790 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 ><th> URI filena
217a0 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 mes <th> Results
217b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
217c0 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a e:data.db <td> .
217d0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
217e0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e the file "data.
217f0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 db" in the curre
21800 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a nt directory..**
21810 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
21820 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
21830 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 b<br>.**
21840 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 file:///home/f
21850 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
21860 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 .** fi
21870 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 le://localhost/h
21880 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
21890 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 <br> <td> .**
218a0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 Open the
218b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 database file "
218c0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
218d0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e db"..** <tr><td>
218e0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 file://darkstar
218f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
21900 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
21910 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 An error. "
21920 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 darkstar" is not
21930 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 a recognized au
21940 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e thority..** <tr>
21950 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 <td style="white
21960 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 -space:nowrap">
21970 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
21980 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 e:///C:/Document
21990 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e s%20and%20Settin
219a0 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f gs/fred/Desktop/
219b0 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c data.db.** <
219c0 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 td> Windows only
219d0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 : Open the file
219e0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 "data.db" on fre
219f0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 d's desktop on d
21a00 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 rive.**
21a10 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 C:. Note that t
21a20 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 he %20 escaping
21a30 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 in this example
21a40 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 is not strictly
21a50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 .** nec
21a60 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 essary - space c
21a70 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 haracters can be
21a80 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a used literally.
21a90 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 ** in U
21aa0 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a RI filenames..**
21ab0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
21ac0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 ata.db?mode=ro&c
21ad0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 ache=private <td
21ae0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
21af0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 pen file "data.d
21b00 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
21b10 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 t directory for
21b20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 read-only access
21b30 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 ..** Re
21b40 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
21b50 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
21b60 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 d-cache mode is
21b70 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 enabled by.**
21b80 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 default,
21b90 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 use a private ca
21ba0 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e che..** <tr><td>
21bb0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
21bc0 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 /data.db?vfs=uni
21bd0 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a x-nolock <td>.**
21be0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
21bf0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
21c00 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 data.db". Use th
21c10 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 e special VFS "u
21c20 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 nix-nolock"..**
21c30 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
21c40 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f ta.db?mode=reado
21c50 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 nly <td> .**
21c60 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 An error.
21c70 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f "readonly" is no
21c80 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e t a valid option
21c90 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 for the "mode"
21ca0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f parameter..** </
21cb0 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 table>.**.** ^UR
21cc0 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 I hexadecimal es
21cd0 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 cape sequences (
21ce0 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 %HH) are support
21cf0 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 ed within the pa
21d00 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 th and.** query
21d10 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 components of a
21d20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d URI. A hexadecim
21d30 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
21d40 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 ce consists of a
21d50 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e .** percent sign
21d60 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 - "%" - followe
21d70 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f d by exactly two
21d80 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 hexadecimal dig
21d90 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 its .** specifyi
21da0 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 ng an octet valu
21db0 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 e. ^Before the p
21dc0 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d ath or query com
21dd0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 ponents of a.**
21de0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 URI filename are
21df0 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 interpreted, th
21e00 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 ey are encoded u
21e10 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 sing UTF-8 and a
21e20 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d ll .** hexadecim
21e30 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
21e40 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 ces replaced by
21e50 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f a single byte co
21e60 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
21e70 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 corresponding oc
21e80 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f tet. If this pro
21e90 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 cess generates a
21ea0 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 n invalid UTF-8
21eb0 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 encoding,.** the
21ec0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
21ed0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 efined..**.** <b
21ee0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
21ef0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
21f00 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
21f10 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
21f20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
21f30 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
21f40 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
21f50 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
21f60 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
21f70 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
21f80 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
21f90 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
21fa0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
21fb0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
21fc0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
21fd0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
21fe0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
21ff0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
22000 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
22010 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
22020 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
22030 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
22040 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
22050 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
22060 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
22070 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
22080 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f alling sqlite3_o
22090 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
220a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 _open_v2(). Oth
220b0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
220c0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
220d0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
220e0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
220f0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a les may fail..**
22100 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
22110 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
22120 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 ctory].*/.int sq
22130 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
22140 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
22150 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
22160 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
22170 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
22180 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
22190 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
221a0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
221b0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
221c0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
221d0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
221e0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
221f0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
22200 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
22210 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
22220 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
22230 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
22240 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. 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 2c 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 20 20 69 6e b handle */. in
222c0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
222d0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
222e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
222f0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
22300 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
22310 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
22320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22330 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f Obtain Values Fo
22340 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 r URI Parameters
22350 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
22360 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 utility routine
22370 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 s, useful to VFS
22380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
22390 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 , that check.**
223a0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 to see if a data
223b0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 base file was a
223c0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e URI that contain
223d0 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 ed a specific qu
223e0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ery .** paramete
223f0 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 r, and if so obt
22400 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f ains the value o
22410 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 f that query par
22420 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 ameter..**.** If
22430 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 F is the databa
22440 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e se filename poin
22450 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ter passed into
22460 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 the xOpen() meth
22470 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 od of .** a VFS
22480 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
22490 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 hen the flags pa
224a0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
224b0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a () has one or .*
224c0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 * more of the [S
224d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
224e0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or [SQLITE_OPEN_
224f0 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 MAIN_DB] bits se
22500 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 t and.** P is th
22510 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 e name of the qu
22520 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 ery parameter, t
22530 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 hen.** sqlite3_u
22540 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 ri_parameter(F,P
22550 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 ) returns the va
22560 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 lue of the P.**
22570 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 parameter if it
22580 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c exists or a NULL
22590 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f pointer if P do
225a0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 es not appear as
225b0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 a .** query par
225c0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 ameter on F. If
225d0 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 P is a query pa
225e0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 rameter of F.**
225f0 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 has no explicit
22600 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 value, then sqli
22610 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
22620 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a r(F,P) returns.*
22630 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
22640 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a n empty string..
22650 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
22660 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
22670 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 P,B) routine ass
22680 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 umes that P is a
22690 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 boolean.** para
226a0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e meter and return
226b0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 s true (1) or fa
226c0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e lse (0) accordin
226d0 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a g to the value.*
226e0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c * of P. The sql
226f0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
22700 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
22710 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 returns true (1)
22720 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 if the.** value
22730 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 of query parame
22740 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 ter P is one of
22750 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f "yes", "true", o
22760 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a r "on" in any.**
22770 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 case or if the
22780 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 value begins wit
22790 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d h a non-zero num
227a0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 ber. The .** sq
227b0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
227c0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
227d0 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 s returns false
227e0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 (0) if the value
227f0 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 of.** query par
22800 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
22810 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 of "no", "false"
22820 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e , or "off" in an
22830 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 y case or.** if
22840 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
22850 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 with a numeric
22860 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e zero. If P is n
22870 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 ot a query.** pa
22880 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 rameter on F or
22890 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 if the value of
228a0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 P is does not ma
228b0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a tch any of the.*
228c0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 * above, then sq
228d0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
228e0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 n(F,P,B) returns
228f0 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 (B!=0)..**.** T
22900 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 he sqlite3_uri_i
22910 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 nt64(F,P,D) rout
22920 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ine converts the
22930 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f value of P into
22940 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 a.** 64-bit sig
22950 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 ned integer and
22960 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 returns that int
22970 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 eger, or D if P
22980 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 does not.** exis
22990 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 t. If the value
229a0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 of P is somethi
229b0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e ng other than an
229c0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a integer, then.*
229d0 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e * zero is return
229e0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 ed..** .** If F
229f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
22a00 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f r, then sqlite3_
22a10 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
22a20 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 P) returns NULL
22a30 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 and.** sqlite3_u
22a40 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
22a50 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 ) returns B. If
22a60 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c F is not a NULL
22a70 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 pointer and.**
22a80 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
22a90 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 e file pathname
22aa0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c pointer that SQL
22ab0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ite passed into
22ac0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 the xOpen.** VFS
22ad0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 method, then th
22ae0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
22af0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e is routine is un
22b00 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
22b10 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 ably.** undesira
22b20 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ble..*/.const ch
22b30 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f ar *sqlite3_uri_
22b40 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 parameter(const
22b50 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c char *zFilename,
22b60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
22b70 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ram);.int sqlite
22b80 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 3_uri_boolean(co
22b90 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c nst char *zFile,
22ba0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
22bb0 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c ram, int bDefaul
22bc0 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 t);.sqlite3_int6
22bd0 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 4 sqlite3_uri_in
22be0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c t64(const char*,
22bf0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 const char*, sq
22c00 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a lite3_int64);...
22c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
22c20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
22c30 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e Messages.**.** ^
22c40 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 The sqlite3_errc
22c50 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ode() interface
22c60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
22c70 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 ric [result code
22c80 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
22c90 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 d result code] f
22ca0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 or the most rece
22cb0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 nt failed sqlite
22cc0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 3_* API call.**
22cd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
22ce0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
22cf0 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 ection]. If a pr
22d00 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 ior API call fai
22d10 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d led.** but the m
22d20 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 ost recent API c
22d30 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 all succeeded, t
22d40 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
22d50 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f from.** sqlite3_
22d60 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 errcode() is und
22d70 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 efined. ^The sq
22d80 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
22d90 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
22da0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
22db0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
22dc0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
22dd0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
22de0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
22df0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
22e00 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
22e10 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
22e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
22e30 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
22e40 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
22e50 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
22e60 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
22e70 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
22e80 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
22e90 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
22ea0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
22eb0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 ely..** ^(Memory
22ec0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
22ed0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
22ee0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
22ef0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
22f00 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
22f10 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
22f20 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 ry about freeing
22f30 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
22f40 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 However, the err
22f50 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 or string might
22f60 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f be overwritten o
22f70 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 r deallocated by
22f80 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 .** subsequent c
22f90 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 alls to other SQ
22fa0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 Lite interface f
22fb0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a unctions.)^.**.*
22fc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
22fd0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 rrstr() interfac
22fe0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e e returns the En
22ff0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
23000 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 ext.** that desc
23010 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c ribes the [resul
23020 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d t code], as UTF-
23030 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 8..** ^(Memory t
23040 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
23050 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
23060 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
23070 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 nally.** and mus
23080 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 t not be freed b
23090 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
230a0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 n)^..**.** When
230b0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
230c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
230d0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
230e0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
230f0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
23100 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
23110 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
23120 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
23130 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
23140 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
23150 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
23160 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
23170 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
23180 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
23190 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
231a0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
231b0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
231c0 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
231d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
231e0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
231f0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
23200 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
23210 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
23220 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
23230 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
23240 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
23250 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
23260 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
23270 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
23280 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
23290 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
232a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
232b0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
232c0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
232d0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
232e0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
232f0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
23300 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
23310 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
23320 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
23330 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
23340 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
23350 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
23360 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
23370 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
23380 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
23390 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
233a0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
233b0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
233c0 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
233d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
233e0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
233f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
23400 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
23410 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
23420 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
23430 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
23440 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
23450 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
23460 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
23470 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
23480 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a rrstr(int);../*.
23490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
234a0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
234b0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
234c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
234d0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 nt} {prepared st
234e0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 atements}.**.**
234f0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
23500 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
23510 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 sents a single S
23520 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a QL statement..**
23530 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 This object is
23540 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 variously known
23550 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 as a "prepared s
23560 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a tatement" or a.*
23570 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 * "compiled SQL
23580 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 statement" or si
23590 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 mply as a "state
235a0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment"..**.** The
235b0 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 life of a state
235c0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 ment object goes
235d0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 something like
235e0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e this:.**.** <ol>
235f0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 .** <li> Create
23600 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
23610 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
23620 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c e_v2()] or a rel
23630 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e ated.** fun
23640 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 ction..** <li> B
23650 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 ind values to [h
23660 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 ost parameters]
23670 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
23680 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 3_bind_*().**
23690 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a interfaces..*
236a0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 * <li> Run the S
236b0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 QL by calling [s
236c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
236d0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
236e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 ..** <li> Reset
236f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 the statement us
23700 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
23710 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 et()] then go ba
23720 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 ck.** to st
23730 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a ep 2. Do this z
23740 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 ero or more time
23750 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 s..** <li> Destr
23760 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 oy the object us
23770 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
23780 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f alize()]..** </o
23790 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 l>.**.** Refer t
237a0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 o documentation
237b0 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 on individual me
237c0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 thods above for
237d0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
237e0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 formation..*/.ty
237f0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
23800 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
23810 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
23820 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
23830 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e e Limits.**.** ^
23840 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 (This interface
23850 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 allows the size
23860 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 of various const
23870 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 ructs to be limi
23880 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e ted.** on a conn
23890 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 ection by connec
238a0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 tion basis. The
238b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
238c0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 is the.** [data
238d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
238e0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 whose limit is
238f0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 to be set or que
23900 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ried. The.** se
23910 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
23920 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 s one of the [li
23930 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 mit categories]
23940 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a that define a.**
23950 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 class of constr
23960 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 ucts to be size
23970 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 limited. The th
23980 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
23990 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 the.** new limi
239a0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 t for that const
239b0 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 ruct.)^.**.** ^I
239c0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 f the new limit
239d0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 is a negative nu
239e0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 mber, the limit
239f0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a is unchanged..**
23a00 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 ^(For each limi
23a10 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 t category SQLIT
23a20 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c E_LIMIT_<i>NAME<
23a30 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a /i> there is a .
23a40 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 ** [limits | har
23a50 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a d upper bound].*
23a60 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 * set at compile
23a70 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 -time by a C pre
23a80 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
23a90 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 called.** [limit
23aa0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c s | SQLITE_MAX_<
23ab0 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 i>NAME</i>]..**
23ac0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 (The "_LIMIT_" i
23ad0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 n the name is ch
23ae0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 anged to "_MAX_"
23af0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 .))^.** ^Attempt
23b00 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
23b10 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
23b20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
23b30 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
23b40 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
23b50 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 e hard upper bou
23b60 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 nd..**.** ^Regar
23b70 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
23b80 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 or not the limi
23b90 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 t was changed, t
23ba0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f he .** [sqlite3_
23bb0 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 limit()] interfa
23bc0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 ce returns the p
23bd0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 rior value of th
23be0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e e limit..** ^Hen
23bf0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 ce, to find the
23c00 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
23c10 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 a limit without
23c20 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a changing it,.**
23c30 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 simply invoke t
23c40 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 his interface wi
23c50 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 th the third par
23c60 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 ameter set to -1
23c70 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 ..**.** Run-time
23c80 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 limits are inte
23c90 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
23ca0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
23cb0 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 t manage.** both
23cc0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 their own inter
23cd0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 nal database and
23ce0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 also databases
23cf0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c that are control
23d00 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 led.** by untrus
23d10 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 ted external sou
23d20 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c rces. An exampl
23d30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
23d40 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 ght be a.** web
23d50 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
23d60 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
23d70 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
23d80 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
23d90 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
23da0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
23db0 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
23dc0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
23dd0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
23de0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
23df0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
23e00 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
23e10 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
23e20 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
23e30 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
23e40 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
23e50 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
23e60 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
23e70 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
23e80 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
23e90 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
23ea0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
23eb0 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
23ec0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
23ed0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
23ee0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
23ef0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
23f00 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
23f10 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
23f20 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
23f30 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
23f40 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
23f50 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
23f60 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
23f70 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
23f80 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
23f90 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
23fa0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
23fb0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
23fc0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
23fd0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
23fe0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
23ff0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
24000 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
24010 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
24020 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
24030 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
24040 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
24050 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {*limit categori
24060 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
24070 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
24080 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
24090 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
240a0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
240b0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
240c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
240d0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
240e0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
240f0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
24100 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
24110 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
24120 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
24130 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
24140 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
24150 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
24160 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
24170 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
24180 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 T_LENGTH]] ^(<dt
24190 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 >SQLITE_LIMIT_LE
241a0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
241b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a >The maximum siz
241c0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 e of any string
241d0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 or BLOB or table
241e0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c row, in bytes.<
241f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
24200 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
24210 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
24220 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
24230 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
24240 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
24250 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 ngth of an SQL s
24260 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 tatement, in byt
24270 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a es.</dd>)^.**.**
24280 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
24290 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 COLUMN]] ^(<dt>S
242a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
242b0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 MN</dt>.** <dd>T
242c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
242d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
242e0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 a table definiti
242f0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 on or in the.**
24300 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
24310 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 [SELECT] or the
24320 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
24330 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 f columns in an
24340 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 index.** or in a
24350 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 n ORDER BY or GR
24360 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f OUP BY clause.</
24370 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
24380 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
24390 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
243a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
243b0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
243c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
243d0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
243e0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
243f0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a ression.</dd>)^.
24400 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
24410 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
24420 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LECT]] ^(<dt>SQL
24430 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
24440 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
24450 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
24460 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
24470 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
24480 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
24490 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
244a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 [SQLITE_LIMIT_VD
244b0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 BE_OP]] ^(<dt>SQ
244c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
244d0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OP</dt>.** <dd>T
244e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
244f0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e r of instruction
24500 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d s in a virtual m
24510 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a achine program.*
24520 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d * used to implem
24530 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 ent an SQL state
24540 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 ment. This limi
24550 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 t is not current
24560 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 ly.** enforced,
24570 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 though that migh
24580 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f t be added in so
24590 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
245a0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c e of.** SQLite.<
245b0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
245c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
245d0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 TION_ARG]] ^(<dt
245e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
245f0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
24600 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
24610 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
24620 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
24630 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tion.</dd>)^.**.
24640 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
24650 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c T_ATTACHED]] ^(<
24660 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
24670 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a ATTACHED</dt>.**
24680 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
24690 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 number of [ATTA
246a0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 CH | attached da
246b0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e tabases].)^</dd>
246c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
246d0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
246e0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e RN_LENGTH]].** ^
246f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
24700 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
24710 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
24720 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
24730 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
24740 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
24750 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a the [LIKE] or.**
24760 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
24770 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
24780 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [[SQLITE_LIMIT_V
24790 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d ARIABLE_NUMBER]]
247a0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
247b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
247c0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c NUMBER</dt>.** <
247d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 dd>The maximum i
247e0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 ndex number of a
247f0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 ny [parameter] i
24800 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
24810 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 nt.)^.**.** [[SQ
24820 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
24830 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 ER_DEPTH]] ^(<dt
24840 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 >SQLITE_LIMIT_TR
24850 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e IGGER_DEPTH</dt>
24860 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
24870 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
24880 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
24890 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c ers.</dd>)^.** <
248a0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
248b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
248c0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
248d0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 0.#define
248e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 SQLITE_LIMIT_SQ
248f0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 L_LENGTH
24900 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
24910 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
24920 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 OLUMN
24930 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
24940 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
24950 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 EXPR_DEPTH
24960 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 3.#def
24970 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
24980 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
24990 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 4.#de
249a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
249b0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 T_VDBE_OP
249c0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
249d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
249e0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 IT_FUNCTION_ARG
249f0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 6.#
24a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
24a10 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 MIT_ATTACHED
24a20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 7.
24a30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
24a40 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 IMIT_LIKE_PATTER
24a50 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 N_LENGTH 8
24a60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24a70 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
24a80 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 UMBER
24a90 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
24aa0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
24ab0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 EPTH
24ac0 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 10../*.** CAPI3R
24ad0 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
24ae0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
24af0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
24b00 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
24b10 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 ler}.**.** To ex
24b20 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 ecute an SQL que
24b30 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 ry, it must firs
24b40 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e t be compiled in
24b50 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a to a byte-code.*
24b60 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 * program using
24b70 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 one of these rou
24b80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tines..**.** The
24b90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c first argument,
24ba0 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 "db", is a [dat
24bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24bc0 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 ] obtained from
24bd0 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 a.** prior succe
24be0 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 ssful call to [s
24bf0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
24c00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
24c10 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
24c20 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 e3_open16()]. T
24c30 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
24c40 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 ection must not
24c50 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 have been closed
24c60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f ..**.** The seco
24c70 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 nd argument, "zS
24c80 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 ql", is the stat
24c90 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
24ca0 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a iled, encoded.**
24cb0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
24cc0 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 or UTF-16. The
24cd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
24ce0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
24cf0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 repare_v2().** i
24d00 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 nterfaces use UT
24d10 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 F-8, and sqlite3
24d20 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 _prepare16() and
24d30 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
24d40 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 16_v2().** use U
24d50 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 TF-16..**.** ^If
24d60 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d the nByte argum
24d70 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e ent is less than
24d80 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c zero, then zSql
24d90 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 is read up to t
24da0 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f he.** first zero
24db0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 terminator. ^If
24dc0 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 nByte is non-ne
24dd0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 gative, then it
24de0 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a is the maximum.*
24df0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 * number of byt
24e00 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 es read from zSq
24e10 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 l. ^When nByte
24e20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
24e30 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 the.** zSql str
24e40 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 ing ends at eith
24e50 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 er the first '\0
24e60 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 00' or '\u0000'
24e70 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 character or.**
24e80 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 the nByte-th byt
24e90 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d e, whichever com
24ea0 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 es first. If the
24eb0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a caller knows.**
24ec0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 that the suppli
24ed0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c ed string is nul
24ee0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 -terminated, the
24ef0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 n there is a sma
24f00 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 ll.** performanc
24f10 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 e advantage to b
24f20 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 e gained by pass
24f30 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 ing an nByte par
24f40 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 ameter that.** i
24f50 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e s equal to the n
24f60 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
24f70 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 n the input stri
24f80 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c ng <i>including<
24f90 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 /i>.** the nul-t
24fa0 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 erminator bytes
24fb0 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 as this saves SQ
24fc0 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 Lite from having
24fd0 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f to.** make a co
24fe0 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 py of the input
24ff0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 string..**.** ^I
25000 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 f pzTail is not
25010 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 NULL then *pzTai
25020 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 l is made to poi
25030 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 nt to the first
25040 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 byte.** past the
25050 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 end of the firs
25060 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
25070 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 in zSql. These
25080 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a routines only.**
25090 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 compile the fir
250a0 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 st statement in
250b0 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c zSql, so *pzTail
250c0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e is left pointin
250d0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d g to.** what rem
250e0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e ains uncompiled.
250f0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 .**.** ^*ppStmt
25100 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 is left pointing
25110 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b to a compiled [
25120 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25130 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a nt] that can be.
25140 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e ** executed usin
25150 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
25160 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 )]. ^If there i
25170 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 s an error, *ppS
25180 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f tmt is set.** to
25190 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 NULL. ^If the
251a0 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 input text conta
251b0 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 ins no SQL (if t
251c0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 he input is an e
251d0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f mpty.** string o
251e0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 r a comment) the
251f0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 n *ppStmt is set
25200 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 to NULL..** The
25210 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 calling procedu
25220 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c re is responsibl
25230 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 e for deleting t
25240 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 he compiled.** S
25250 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 QL statement usi
25260 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ng [sqlite3_fina
25270 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 lize()] after it
25280 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
25290 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 th it..** ppStmt
252a0 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c may not be NULL
252b0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 ..**.** ^On succ
252c0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ess, the sqlite3
252d0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c _prepare() famil
252e0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 y of routines re
252f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
25300 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 ;.** otherwise a
25310 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 n [error code] i
25320 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
25330 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 * The sqlite3_pr
25340 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 epare_v2() and s
25350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
25360 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 _v2() interfaces
25370 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e are.** recommen
25380 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 ded for all new
25390 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 programs. The tw
253a0 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 o older interfac
253b0 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a es are retained.
253c0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ** for backwards
253d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 compatibility,
253e0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 but their use is
253f0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a discouraged..**
25400 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e ^In the "v2" in
25410 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 terfaces, the pr
25420 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25430 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 .** that is retu
25440 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 rned (the [sqlit
25450 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 e3_stmt] object)
25460 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 contains a copy
25470 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 of the.** origi
25480 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 nal SQL text. Th
25490 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 is causes the [s
254a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 qlite3_step()] i
254b0 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 nterface to.** b
254c0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c ehave differentl
254d0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a y in three ways:
254e0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
254f0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 li>.** ^If the d
25500 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
25510 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 hanges, instead
25520 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 of returning [SQ
25530 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 LITE_SCHEMA] as
25540 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 it.** always use
25550 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 d to do, [sqlite
25560 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 3_step()] will a
25570 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 utomatically rec
25580 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a ompile the SQL.*
25590 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 * statement and
255a0 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 try to run it ag
255b0 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 ain. As many as
255c0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 [SQLITE_MAX_SCHE
255d0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 MA_RETRY].** ret
255e0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 ries will occur
255f0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 before sqlite3_s
25600 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 tep() gives up a
25610 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 nd returns an er
25620 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a ror..** </li>.**
25630 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 .** <li>.** ^Whe
25640 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 n an error occur
25650 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 s, [sqlite3_step
25660 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
25670 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 one of the detai
25680 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f led.** [error co
25690 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 des] or [extende
256a0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 d error codes].
256b0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 ^The legacy beh
256c0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a avior was that.*
256d0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
256e0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 )] would only re
256f0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b turn a generic [
25700 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 SQLITE_ERROR] re
25710 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 sult code.** and
25720 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
25730 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d would have to m
25740 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c ake a second cal
25750 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 l to [sqlite3_re
25760 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 set()].** in ord
25770 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 er to find the u
25780 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 nderlying cause
25790 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 of the problem.
257a0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 With the "v2" pr
257b0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 epare.** interfa
257c0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 ces, the underly
257d0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 ing reason for t
257e0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 he error is retu
257f0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 rned immediately
25800 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a ..** </li>.**.**
25810 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 <li>.** ^If the
25820 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 specific value
25830 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 bound to [parame
25840 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d ter | host param
25850 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a eter] in the .**
25860 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 WHERE clause mi
25870 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 ght influence th
25880 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 e choice of quer
25890 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 y plan for a sta
258a0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 tement,.** then
258b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 the statement wi
258c0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
258d0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 lly recompiled,
258e0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 as if there had
258f0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d been .** a schem
25900 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 a change, on the
25910 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 first [sqlite3
25920 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f _step()] call fo
25930 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e llowing any chan
25940 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 ge.** to the [sq
25950 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 lite3_bind_text
25960 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 | bindings] of t
25970 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e hat [parameter].
25980 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 .** ^The specif
25990 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 ic value of WHER
259a0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 E-clause [parame
259b0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 ter] might influ
259c0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f ence the .** cho
259d0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 ice of query pla
259e0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 n if the paramet
259f0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 er is the left-h
25a00 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c and side of a [L
25a10 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 IKE].** or [GLOB
25a20 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 ] operator or if
25a30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
25a40 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e s compared to an
25a50 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a indexed column.
25a60 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 ** and the [SQLI
25a70 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d TE_ENABLE_STAT3]
25a80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
25a90 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e tion is enabled.
25aa0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 .** the .** </li
25ab0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e >.** </ol>.*/.in
25ac0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
25ad0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
25ae0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
25af0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
25b00 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
25b10 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
25b20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
25b30 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
25b40 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
25b50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
25b60 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
25b70 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
25b80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
25b90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
25ba0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
25bb0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
25bc0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
25bd0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
25be0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
25bf0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
25c00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
25c10 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 pare_v2(. sqlit
25c20 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
25c30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
25c40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
25c50 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
25c60 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
25c70 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
25c80 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
25c90 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
25ca0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
25cb0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
25cc0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
25cd0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
25ce0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
25cf0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
25d00 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
25d10 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
25d20 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
25d30 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
25d40 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
25d50 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
25d60 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
25d70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
25d80 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
25d90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
25da0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
25db0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
25dc0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
25dd0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
25de0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
25df0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
25e00 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
25e10 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
25e20 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
25e30 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
25e40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
25e50 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
25e60 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
25e70 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
25e80 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
25e90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
25ea0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 16_v2(. sqlite3
25eb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
25ec0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
25ed0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
25ee0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
25ef0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
25f00 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
25f10 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
25f20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
25f30 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
25f40 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
25f50 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
25f60 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
25f70 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
25f80 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
25f90 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
25fa0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
25fb0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
25fc0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
25fd0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
25fe0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e I3REF: Retrievin
25ff0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a g Statement SQL.
26000 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
26010 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
26020 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
26030 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
26040 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
26050 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
26060 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
26070 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
26080 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
26090 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
260a0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
260b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
260c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
260d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
260e0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
260f0 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 qlite3_sql(sqlit
26100 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
26110 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26120 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
26130 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
26140 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 Writes The Datab
26150 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ase.**.** ^The s
26160 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
26170 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 only(X) interfac
26180 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
26190 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 non-zero) if.**
261a0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 and only if the
261b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
261c0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 ent] X makes no
261d0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 direct changes t
261e0 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 o.** the content
261f0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
26200 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 file..**.** Not
26210 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 e that [applicat
26220 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
26230 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a functions] or.**
26240 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 [virtual tables
26250 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 ] might change t
26260 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 he database indi
26270 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 rectly as a side
26280 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 effect. .** ^(
26290 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 For example, if
262a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 an application d
262b0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f efines a functio
262c0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 n "eval()" that
262d0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 .** calls [sqlit
262e0 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e e3_exec()], then
262f0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
26300 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 QL statement wou
26310 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 ld.** change the
26320 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
26330 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 hrough side-effe
26340 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 cts:.**.** <bloc
26350 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
26360 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 SELECT eval('
26370 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 DELETE FROM t1')
26380 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 FROM t2;.** </p
26390 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
263a0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 .**.** But becau
263b0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 se the [SELECT]
263c0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
263d0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ot change the da
263e0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 tabase file.** d
263f0 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 irectly, sqlite3
26400 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
26410 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 would still ret
26420 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a urn true.)^.**.*
26430 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 * ^Transaction c
26440 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 ontrol statement
26450 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e s such as [BEGIN
26460 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f ], [COMMIT], [RO
26470 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 LLBACK],.** [SAV
26480 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 EPOINT], and [RE
26490 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c LEASE] cause sql
264a0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
264b0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
264c0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 rue,.** since th
264d0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 e statements the
264e0 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 mselves do not a
264f0 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 ctually modify t
26500 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a he database but.
26510 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 ** rather they c
26520 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e ontrol the timin
26530 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 g of when other
26540 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 statements modif
26550 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 y the .** databa
26560 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 se. ^The [ATTAC
26570 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 H] and [DETACH]
26580 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 statements also
26590 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 cause.** sqlite3
265a0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
265b0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 to return true
265c0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f since, while tho
265d0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a se statements.**
265e0 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 change the conf
265f0 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 iguration of a d
26600 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26610 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 on, they do not
26620 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 make .** changes
26630 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 to the content
26640 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
26650 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a files on disk..*
26660 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 /.int sqlite3_st
26670 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 mt_readonly(sqli
26680 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
26690 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
266a0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
266b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
266c0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 ment Has Been Re
266d0 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 set.**.** ^The s
266e0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
266f0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (S) interface re
26700 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
26710 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 zero) if the.**
26720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
26730 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 ent] S has been
26740 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 stepped at least
26750 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 once using .**
26760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
26770 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 ] but has not ru
26780 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 n to completion
26790 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a and/or has not .
267a0 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 ** been reset us
267b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
267c0 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 et(S)]. ^The sq
267d0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
267e0 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 S).** interface
267f0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 returns false if
26800 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 S is a NULL poi
26810 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e nter. If S is n
26820 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f ot a .** NULL po
26830 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 inter and is not
26840 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
26850 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 valid [prepared
26860 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
26870 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 ject, then the b
26880 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
26890 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c ined and probabl
268a0 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a y undesirable..*
268b0 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 *.** This interf
268c0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
268d0 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b in combination [
268e0 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d sqlite3_next_stm
268f0 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 t()].** to locat
26900 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 e all prepared s
26910 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 tatements associ
26920 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 ated with a data
26930 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 base .** connect
26940 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 ion that are in
26950 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 need of being re
26960 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 set. This can b
26970 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 e used,.** for e
26980 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e xample, in diagn
26990 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 ostic routines t
269a0 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 o search for pre
269b0 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d pared .** statem
269c0 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f ents that are ho
269d0 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 lding a transact
269e0 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 ion open..*/.int
269f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
26a00 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a sy(sqlite3_stmt*
26a10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
26a20 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 EF: Dynamically
26a30 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 Typed Value Obje
26a40 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ct.** KEYWORDS:
26a50 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 {protected sqlit
26a60 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f e3_value} {unpro
26a70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
26a80 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 alue}.**.** SQLi
26a90 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 te uses the sqli
26aa0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
26ab0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c to represent al
26ac0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 l values.** that
26ad0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 can be stored i
26ae0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
26af0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 le. SQLite uses
26b00 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a dynamic typing.*
26b10 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 * for the values
26b20 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 it stores. ^Va
26b30 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 lues stored in s
26b40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
26b50 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 ects.** can be i
26b60 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e ntegers, floatin
26b70 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 g point values,
26b80 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 strings, BLOBs,
26b90 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 or NULL..**.** A
26ba0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
26bb0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 object may be ei
26bc0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 ther "protected"
26bd0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 or "unprotected
26be0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 "..** Some inter
26bf0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 faces require a
26c00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
26c10 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 3_value. Other
26c20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 interfaces.** wi
26c30 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 ll accept either
26c40 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 a protected or
26c50 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 an unprotected s
26c60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a qlite3_value..**
26c70 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 Every interface
26c80 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 that accepts sq
26c90 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 lite3_value argu
26ca0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a ments specifies.
26cb0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f ** whether or no
26cc0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 t it requires a
26cd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
26ce0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 3_value..**.** T
26cf0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 he terms "protec
26d00 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 ted" and "unprot
26d10 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 ected" refer to
26d20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a whether or not.*
26d30 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c * a mutex is hel
26d40 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 d. An internal
26d50 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f mutex is held fo
26d60 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a r a protected.**
26d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
26d80 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 bject but no mut
26d90 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 ex is held for a
26da0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a n unprotected.**
26db0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
26dc0 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 bject. If SQLit
26dd0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f e is compiled to
26de0 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 be single-threa
26df0 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 ded.** (with [SQ
26e00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
26e10 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 0] and with [sql
26e20 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
26e30 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a )] returning 0).
26e40 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 ** or if SQLite
26e50 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 is run in one of
26e60 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d reduced mutex m
26e70 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 odes .** [SQLITE
26e80 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
26e90 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 READ] or [SQLITE
26ea0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
26eb0 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 EAD].** then the
26ec0 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 re is no distinc
26ed0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f tion between pro
26ee0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
26ef0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
26f00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
26f10 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 and they can be
26f20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 used interchange
26f30 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a ably. However,.
26f40 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 ** for maximum c
26f50 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 ode portability
26f60 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
26f70 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
26f80 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b ons.** still mak
26f90 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f e the distinctio
26fa0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
26fb0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
26fc0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
26fd0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 alue objects eve
26fe0 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 n when not stric
26ff0 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a tly required..**
27000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27010 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 _value objects t
27020 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 hat are passed a
27030 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 s parameters int
27040 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 o the.** impleme
27050 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c ntation of [appl
27060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27070 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 SQL functions] a
27080 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a re protected..**
27090 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
270a0 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 lue object retur
270b0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
270c0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
270d0 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 )] is unprotecte
270e0 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 d..** Unprotecte
270f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
27100 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 objects may only
27110 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a be used with.**
27120 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 [sqlite3_result
27130 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
27140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
27150 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 e()]..** The [sq
27160 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 lite3_value_blob
27170 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 | sqlite3_value
27180 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 _type()] family
27190 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 of.** interfaces
271a0 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 require protect
271b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
271c0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 objects..*/.typ
271d0 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 edef struct Mem
271e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a sqlite3_value;..
271f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27200 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e SQL Function Con
27210 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a text Object.**.*
27220 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e * The context in
27230 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 which an SQL fu
27240 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 nction executes
27250 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a is stored in an.
27260 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ** sqlite3_conte
27270 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 xt object. ^A p
27280 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c ointer to an sql
27290 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a ite3_context obj
272a0 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 ect.** is always
272b0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
272c0 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e to [application
272d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
272e0 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 ctions]..** The
272f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
27300 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
27310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
27320 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a will pass this.*
27330 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 * pointer throug
27340 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 h into calls to
27350 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
27360 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 int | sqlite3_re
27370 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c sult()],.** [sql
27380 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
27390 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 ontext()], [sqli
273a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
273b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f ,.** [sqlite3_co
273c0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
273d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 )], [sqlite3_get
273e0 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 _auxdata()],.**
273f0 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f and/or [sqlite3_
27400 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a set_auxdata()]..
27410 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
27420 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
27430 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t sqlite3_contex
27440 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 t;../*.** CAPI3R
27450 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 EF: Binding Valu
27460 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 es To Prepared S
27470 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 tatements.** KEY
27480 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 WORDS: {host par
27490 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 ameter} {host pa
274a0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 rameters} {host
274b0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a parameter name}.
274c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 ** KEYWORDS: {SQ
274d0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 L parameter} {SQ
274e0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 L parameters} {p
274f0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
27500 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 }.**.** ^(In the
27510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
27520 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ext input to [sq
27530 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
27540 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
27550 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c ants,.** literal
27560 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
27570 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 d by a [paramete
27580 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 r] that matches
27590 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 one of following
275a0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a .** templates:.*
275b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
275c0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
275d0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
275e0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
275f0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
27600 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
27610 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f he templates abo
27620 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e ve, NNN represen
27630 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 ts an integer li
27640 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
27650 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 V represents an
27660 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 alphanumeric ide
27670 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 ntifier.)^ ^The
27680 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
27690 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 .** parameters (
276a0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
276b0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
276c0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d s" or "SQL param
276d0 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
276e0 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
276f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
27700 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
27710 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d here..**.** ^T
27720 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
27730 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
27740 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
27750 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 es is always.**
27760 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
27770 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
27780 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
27790 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 from.** [sqlite3
277a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
277b0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a r its variants..
277c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
277d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
277e0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 e index of the S
277f0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 QL parameter to
27800 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 be set..** ^The
27810 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
27820 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
27830 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e dex of 1. ^When
27840 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a the same named.
27850 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
27860 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 is used more th
27870 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 an once, second
27880 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a and subsequent.*
27890 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 * occurrences ha
278a0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 ve the same inde
278b0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f x as the first o
278c0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 ccurrence..** ^T
278d0 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d he index for nam
278e0 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 ed parameters ca
278f0 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 n be looked up u
27900 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
27910 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
27920 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 ter_index()] API
27930 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 if desired. ^T
27940 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 he index.** for
27950 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 "?NNN" parameter
27960 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f s is the value o
27970 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e f NNN..** ^The N
27980 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 NN value must be
27990 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 between 1 and t
279a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 he [sqlite3_limi
279b0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 t()].** paramete
279c0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f r [SQLITE_LIMIT_
279d0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
279e0 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a (default value:
279f0 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 999)..**.** ^Th
27a00 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
27a10 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
27a20 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
27a30 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ameter..**.** ^(
27a40 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 In those routine
27a50 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f s that have a fo
27a60 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 urth argument, i
27a70 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a ts value is the.
27a80 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
27a90 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 es in the parame
27aa0 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 ter. To be clea
27ab0 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 r: the value is
27ac0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
27ad0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e <u>bytes</u> in
27ae0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 the value, not
27af0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
27b00 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e aracters.)^.** ^
27b10 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
27b20 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
27b30 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f e3_bind_text() o
27b40 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
27b50 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 ext16().** is ne
27b60 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
27b70 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
27b80 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
27b90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
27ba0 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
27bb0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
27bc0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 .** If the fourt
27bd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
27be0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
27bf0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 () is negative,
27c00 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 then.** the beha
27c10 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
27c20 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e d..** If a non-n
27c30 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 egative fourth p
27c40 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 arameter is prov
27c50 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ided to sqlite3_
27c60 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f bind_text().** o
27c70 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
27c80 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 ext16() then tha
27c90 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
27ca0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 be the byte off
27cb0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 set.** where the
27cc0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 NUL terminator
27cd0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 would occur assu
27ce0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 ming the string
27cf0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d were NUL.** term
27d00 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 inated. If any
27d10 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f NUL characters o
27d20 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 ccur at byte off
27d30 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a sets less than .
27d40 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ** the value of
27d50 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
27d60 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 eter then the re
27d70 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 sulting string v
27d80 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e alue will.** con
27d90 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 tain embedded NU
27da0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 Ls. The result
27db0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 of expressions i
27dc0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 nvolving strings
27dd0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 .** with embedde
27de0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 d NULs is undefi
27df0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
27e00 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 fifth argument t
27e10 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
27e20 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 lob(), sqlite3_b
27e30 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a ind_text(), and.
27e40 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ** sqlite3_bind_
27e50 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 text16() is a de
27e60 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f structor used to
27e70 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
27e80 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e BLOB or.** strin
27e90 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 g after SQLite h
27ea0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
27eb0 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 it. ^The destr
27ec0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a uctor is called.
27ed0 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 ** to dispose of
27ee0 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 the BLOB or str
27ef0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
27f00 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
27f10 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 bind_blob(),.**
27f20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
27f30 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f t(), or sqlite3_
27f40 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 bind_text16() fa
27f50 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 ils. .** ^If th
27f60 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
27f70 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 is.** the speci
27f80 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 al value [SQLITE
27f90 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 _STATIC], then S
27fa0 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
27fb0 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d at the.** inform
27fc0 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 ation is in stat
27fd0 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
27fe0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
27ff0 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
28000 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 d..** ^If the fi
28010 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 fth argument has
28020 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 the value [SQLI
28030 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 TE_TRANSIENT], t
28040 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 hen.** SQLite ma
28050 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 kes its own priv
28060 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
28070 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 data immediately
28080 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 , before.** the
28090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
280a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
280b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
280c0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
280d0 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e ob() routine bin
280e0 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e ds a BLOB of len
280f0 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 gth N that.** is
28100 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 filled with zer
28110 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f oes. ^A zeroblo
28120 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 b uses a fixed a
28130 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a mount of memory.
28140 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 ** (just an inte
28150 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 ger to hold its
28160 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 size) while it i
28170 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 s being processe
28180 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 d..** Zeroblobs
28190 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 are intended to
281a0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f serve as placeho
281b0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 lders for BLOBs
281c0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 whose.** content
281d0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 is later writte
281e0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 n using.** [sqli
281f0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 te3_blob_open |
28200 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 incremental BLOB
28210 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a I/O] routines..
28220 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 ** ^A negative v
28230 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 alue for the zer
28240 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e oblob results in
28250 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
28260 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 LOB..**.** ^If a
28270 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ny of the sqlite
28280 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
28290 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 nes are called w
282a0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
282b0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 er.** for the [p
282c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
282d0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 t] or with a pre
282e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
282f0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 for which.** [sq
28300 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
28310 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f s been called mo
28320 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e re recently than
28330 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
28340 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 )],.** then the
28350 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e call will return
28360 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
28370 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 . If any sqlite
28380 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 3_bind_().** rou
28390 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 tine is passed a
283a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
283b0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 ment] that has b
283c0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 een finalized, t
283d0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 he.** result is
283e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
283f0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a obably harmful..
28400 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 **.** ^Bindings
28410 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 are not cleared
28420 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
28430 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 reset()] routine
28440 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 ..** ^Unbound pa
28450 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 rameters are int
28460 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c erpreted as NULL
28470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
28480 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 ite3_bind_* rout
28490 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
284a0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
284b0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 ss or an.** [err
284c0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 or code] if anyt
284d0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e hing goes wrong.
284e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e .** ^[SQLITE_RAN
284f0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 GE] is returned
28500 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
28510 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 .** index is out
28520 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 of range. ^[SQ
28530 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 LITE_NOMEM] is r
28540 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f eturned if mallo
28550 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a c() fails..**.**
28560 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
28570 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
28580 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 er_count()],.**
28590 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
285a0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c rameter_name()],
285b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 and [sqlite3_bi
285c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
285d0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ex()]..*/.int sq
285e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 lite3_bind_blob(
285f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
28600 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
28610 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 int n, void(*)(
28620 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c void*));.int sql
28630 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 ite3_bind_double
28640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
28650 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e int, double);.in
28660 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 t sqlite3_bind_i
28670 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
28680 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 , int, int);.int
28690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
286a0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
286b0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
286c0 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 int64);.int sqli
286d0 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 te3_bind_null(sq
286e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
286f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
28700 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 ind_text(sqlite3
28710 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
28720 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c st char*, int n,
28730 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
28740 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
28750 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 nd_text16(sqlite
28760 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
28770 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
28780 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
28790 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
287a0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f d_value(sqlite3_
287b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
287c0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t sqlite3_value*
287d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
287e0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c ind_zeroblob(sql
287f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
28800 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 int n);../*.**
28810 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
28820 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 Of SQL Paramete
28830 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 rs.**.** ^This r
28840 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 outine can be us
28850 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e ed to find the n
28860 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 umber of [SQL pa
28870 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 rameters].** in
28880 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
28890 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 ement]. SQL par
288a0 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 ameters are toke
288b0 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 ns of the.** for
288c0 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 m "?", "?NNN", "
288d0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f :AAA", "$AAA", o
288e0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 r "@AAA" that se
288f0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 rve as.** placeh
28900 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 olders for value
28910 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 s that are [sqli
28920 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
28930 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 bound].** to the
28940 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 parameters at a
28950 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a later time..**.
28960 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e ** ^(This routin
28970 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 e actually retur
28980 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 ns the index of
28990 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 the largest (rig
289a0 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d htmost).** param
289b0 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f eter. For all fo
289c0 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c rms except ?NNN,
289d0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 this will corre
289e0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 spond to the.**
289f0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 number of unique
28a00 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 parameters. If
28a10 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 parameters of t
28a20 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 he ?NNN form are
28a30 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 used,.** there
28a40 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 may be gaps in t
28a50 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a he list.)^.**.**
28a60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
28a70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
28a80 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a lite3_bind()],.*
28a90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
28aa0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
28ab0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
28ac0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
28ad0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 r_index()]..*/.i
28ae0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
28af0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
28b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
28b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
28b20 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 Name Of A Host
28b30 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 Parameter.**.**
28b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
28b50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
28b60 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
28b70 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
28b80 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
28b90 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
28ba0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
28bb0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
28bc0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
28bd0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
28be0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
28bf0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
28c00 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
28c10 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
28c20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
28c30 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
28c40 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
28c50 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
28c60 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
28c70 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
28c80 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
28c90 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
28ca0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
28cb0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
28cc0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
28cd0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
28ce0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
28cf0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
28d00 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
28d10 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
28d20 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
28d30 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
28d40 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
28d50 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
28d60 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
28d70 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
28d80 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
28d90 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
28da0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
28db0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
28dc0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
28dd0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
28de0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
28df0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
28e00 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
28e10 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
28e20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
28e30 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
28e40 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
28e50 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
28e60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
28e70 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
28e80 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
28e90 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 ]..**.** See als
28ea0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
28eb0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 _blob|sqlite3_bi
28ec0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 nd()],.** [sqlit
28ed0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
28ee0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a r_count()], and.
28ef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
28f00 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
28f10 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ()]..*/.const ch
28f20 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 ar *sqlite3_bind
28f30 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
28f40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
28f50 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
28f60 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 3REF: Index Of A
28f70 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 Parameter With
28f80 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a A Given Name.**.
28f90 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 ** ^Return the i
28fa0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 ndex of an SQL p
28fb0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 arameter given i
28fc0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a ts name. ^The.*
28fd0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 * index value re
28fe0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 turned is suitab
28ff0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 le for use as th
29000 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 e second.** para
29010 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 meter to [sqlite
29020 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
29030 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 te3_bind()]. ^A
29040 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 zero.** is retu
29050 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 rned if no match
29060 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 ing parameter is
29070 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 found. ^The pa
29080 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 rameter.** name
29090 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e must be given in
290a0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 UTF-8 even if t
290b0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
290c0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 ement.** was pre
290d0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 pared from UTF-1
290e0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6 text using [sq
290f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
29100 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 v2()]..**.** See
29110 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
29120 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
29130 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
29140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
29150 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 meter_count()],
29160 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
29170 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
29180 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
29190 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
291a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c ameter_index(sql
291b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 ite3_stmt*, cons
291c0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
291d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
291e0 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 Reset All Bindi
291f0 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 ngs On A Prepare
29200 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a d Statement.**.*
29210 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 * ^Contrary to t
29220 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
29230 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
29240 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
29250 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
29260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
29270 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
29280 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
29290 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 ement]..** ^Use
292a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
292b0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 reset all host p
292c0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c arameters to NUL
292d0 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 L..*/.int sqlite
292e0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
292f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
29300 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29310 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 : Number Of Colu
29320 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mns In A Result
29330 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 Set.**.** ^Retur
29340 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 n the number of
29350 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 columns in the r
29360 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e esult set return
29370 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 ed by the.** [pr
29380 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29390 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ]. ^This routine
293a0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 returns 0 if pS
293b0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a tmt is an SQL.**
293c0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
293d0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 does not return
293e0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c data (for exampl
293f0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a e an [UPDATE])..
29400 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
29410 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f [sqlite3_data_co
29420 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 unt()].*/.int sq
29430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
29440 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
29450 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
29460 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e CAPI3REF: Column
29470 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 Names In A Resu
29480 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 lt Set.**.** ^Th
29490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
294a0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 urn the name ass
294b0 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 igned to a parti
294c0 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 cular column.**
294d0 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
294e0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
294f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 statement. ^The
29500 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29510 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 name().** interf
29520 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
29530 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d inter to a zero-
29540 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
29550 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 string.** and s
29560 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
29570 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 me16() returns a
29580 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
29590 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
295a0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 UTF-16 string.
295b0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
295c0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 meter is the [pr
295d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
295e0 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d ].** that implem
295f0 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 ents the [SELECT
29600 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 ] statement. ^Th
29610 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
29620 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c er is the.** col
29630 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 umn number. ^Th
29640 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d e leftmost colum
29650 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a n is number 0..*
29660 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e *.** ^The return
29670 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 ed string pointe
29680 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c r is valid until
29690 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 either the [pre
296a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
296b0 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 .** is destroyed
296c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e by [sqlite3_fin
296d0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
296e0 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 l the statement
296f0 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
29700 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 .** reprepared b
29710 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c y the first call
29720 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
29730 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 p()] for a parti
29740 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 cular run.** or
29750 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 until the next c
29760 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
29770 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 3_column_name()
29780 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
29790 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 n_name16() on th
297a0 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a e same column..*
297b0 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 *.** ^If sqlite3
297c0 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 _malloc() fails
297d0 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 during the proce
297e0 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 ssing of either
297f0 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 routine.** (for
29800 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 example during a
29810 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d conversion from
29820 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 UTF-8 to UTF-16
29830 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c ) then a.** NULL
29840 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
29850 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rned..**.** ^The
29860 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c name of a resul
29870 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 t column is the
29880 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 value of the "AS
29890 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 " clause for.**
298a0 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 that column, if
298b0 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 there is an AS c
298c0 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 lause. If there
298d0 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 is no AS clause
298e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d .** then the nam
298f0 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 e of the column
29900 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 is unspecified a
29910 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 nd may change fr
29920 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 om.** one releas
29930 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 e of SQLite to t
29940 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 he next..*/.cons
29950 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
29960 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
29970 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
29980 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
29990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
299a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
299b0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a t*, int N);../*.
299c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 ** CAPI3REF: Sou
299d0 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 rce Of Data In A
299e0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
299f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
29a00 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 nes provide a me
29a10 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ans to determine
29a20 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 the database, t
29a30 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 able, and.** tab
29a40 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 le column that i
29a50 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 s the origin of
29a60 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 a particular res
29a70 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a ult column in.**
29a80 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
29a90 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ent..** ^The nam
29aa0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
29ab0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f e or table or co
29ac0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 lumn can be retu
29ad0 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 rned as.** eithe
29ae0 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 r a UTF-8 or UTF
29af0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
29b00 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 e _database_ rou
29b10 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tines return.**
29b20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
29b30 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 e, the _table_ r
29b40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
29b50 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 he table name, a
29b60 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e nd.** the origin
29b70 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
29b80 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d n the column nam
29b90 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 e..** ^The retur
29ba0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
29bb0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 lid until the [p
29bc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29bd0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a t] is destroyed.
29be0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
29bf0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
29c00 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
29c10 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
29c20 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
29c30 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
29c40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
29c50 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
29c60 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
29c70 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 * or until the s
29c80 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
29c90 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 is requested.**
29ca0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 again in a diffe
29cb0 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a rent encoding..*
29cc0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 *.** ^The names
29cd0 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 returned are the
29ce0 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 original un-ali
29cf0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 ased names of th
29d00 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 e.** database, t
29d10 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e able, and column
29d20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
29d30 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
29d40 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
29d50 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
29d60 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 tatement]..** ^T
29d70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
29d80 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
29d90 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 n about the Nth
29da0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 result column re
29db0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
29dc0 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
29dd0 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
29de0 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
29df0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 ent..** ^The lef
29e00 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 t-most column is
29e10 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 column 0 for th
29e20 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
29e30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 .** ^If the Nth
29e40 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
29e50 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
29e60 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f is an expressio
29e70 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 n or.** subquery
29e80 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f and is not a co
29e90 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e lumn value, then
29ea0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 all of these fu
29eb0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a nctions return.*
29ec0 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 * NULL. ^These
29ed0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
29ee0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
29ef0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
29f00 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
29f10 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 ccurs. ^Otherwi
29f20 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 se, they return
29f30 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
29f40 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
29f50 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 e, table,.** or
29f60 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 column that quer
29f70 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 y result column
29f80 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 was extracted fr
29f90 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 om..**.** ^As wi
29fa0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c th all other SQL
29fb0 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 ite APIs, those
29fc0 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 whose names end
29fd0 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e with "16" return
29fe0 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 .** UTF-16 encod
29ff0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 ed strings and t
2a000 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f he other functio
2a010 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e ns return UTF-8.
2a020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 .**.** ^These AP
2a030 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 Is are only avai
2a040 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
2a050 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
2a060 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
2a070 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
2a080 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
2a090 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
2a0a0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 bol..**.** If tw
2a0b0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
2a0c0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
2a0d0 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 re of these rout
2a0e0 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 ines against the
2a0f0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 same.** prepare
2a100 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
2a110 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 column at the sa
2a120 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
2a130 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 results are.**
2a140 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2a150 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
2a160 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
2a170 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c or more.** [sql
2a180 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
2a190 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 base_name | colu
2a1a0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 mn metadata inte
2a1b0 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 rfaces].** for t
2a1c0 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 he same [prepare
2a1d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
2a1e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a result column.*
2a1f0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 * at the same ti
2a200 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
2a210 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
2a220 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 d..*/.const char
2a230 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2a240 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 _database_name(s
2a250 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2a260 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2a270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2a280 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 tabase_name16(sq
2a290 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2a2a0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 ;.const char *sq
2a2b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 lite3_column_tab
2a2c0 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f le_name(sqlite3_
2a2d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 stmt*,int);.cons
2a2e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
2a2f0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
2a300 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
2a310 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 *,int);.const ch
2a320 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2a330 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 mn_origin_name(s
2a340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2a350 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2a360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
2a370 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 igin_name16(sqli
2a380 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2a390 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2a3a0 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 Declared Dataty
2a3b0 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 pe Of A Query Re
2a3c0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 sult.**.** ^(The
2a3d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
2a3e0 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 is a [prepared
2a3f0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 statement]..** I
2a400 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 f this statement
2a410 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 is a [SELECT] s
2a420 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 tatement and the
2a430 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
2a440 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 he.** returned r
2a450 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 esult set of tha
2a460 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 t [SELECT] is a
2a470 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f table column (no
2a480 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 t an.** expressi
2a490 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 on or subquery)
2a4a0 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 then the declare
2a4b0 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 d type of the ta
2a4c0 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 ble.** column is
2a4d0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 returned.)^ ^I
2a4e0 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e f the Nth column
2a4f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2a500 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 et is an.** expr
2a510 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
2a520 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 ry, then a NULL
2a530 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 pointer is retur
2a540 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ned..** ^The ret
2a550 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2a560 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 always UTF-8 enc
2a570 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f oded..**.** ^(Fo
2a580 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e r example, given
2a590 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
2a5a0 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 hema:.**.** CREA
2a5b0 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 TE TABLE t1(c1 V
2a5c0 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 ARIANT);.**.** a
2a5d0 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 nd the following
2a5e0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
2a5f0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a compiled:.**.**
2a600 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 SELECT c1 + 1,
2a610 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a c1 FROM t1;.**.*
2a620 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 * this routine w
2a630 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
2a640 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 string "VARIANT"
2a650 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 for the second
2a660 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e result.** column
2a670 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e (i==1), and a N
2a680 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 ULL pointer for
2a690 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 the first result
2a6a0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 column (i==0).)
2a6b0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ^.**.** ^SQLite
2a6c0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e uses dynamic run
2a6d0 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e -time typing. ^
2a6e0 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 So just because
2a6f0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 a column.** is d
2a700 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 eclared to conta
2a710 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 in a particular
2a720 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 type does not me
2a730 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 an that the.** d
2a740 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 ata stored in th
2a750 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 at column is of
2a760 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
2a770 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a e. SQLite is.**
2a780 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c strongly typed,
2a790 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 but the typing
2a7a0 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 is dynamic not s
2a7b0 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a tatic. ^Type.**
2a7c0 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 is associated w
2a7d0 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 ith individual v
2a7e0 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 alues, not with
2a7f0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a the containers.*
2a800 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 * used to hold t
2a810 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a hose values..*/.
2a820 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2a830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
2a840 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ype(sqlite3_stmt
2a850 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f *,int);.const vo
2a860 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
2a870 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 mn_decltype16(sq
2a880 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2a890 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a8a0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 F: Evaluate An S
2a8b0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a QL Statement.**.
2a8c0 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
2a8d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2a8e0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
2a8f0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a d using either.*
2a900 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2a910 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
2a920 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2a930 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 2()] or one of t
2a940 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
2a950 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
2a960 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b _prepare()] or [
2a970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a980 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 6()], this funct
2a990 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 ion.** must be c
2a9a0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
2a9b0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 e times to evalu
2a9c0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
2a9d0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
2a9e0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
2a9f0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 vior of the sqli
2aa00 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 te3_step() inter
2aa10 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f face depend.** o
2aa20 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 n whether the st
2aa30 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 atement was prep
2aa40 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e ared using the n
2aa50 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 ewer "v2" interf
2aa60 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ace.** [sqlite3_
2aa70 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2aa80 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
2aa90 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 re16_v2()] or th
2aaa0 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a e older legacy.*
2aab0 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c * interface [sql
2aac0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2aad0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2aae0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
2aaf0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
2ab00 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 w "v2" interface
2ab10 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
2ab20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
2ab30 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
2ab40 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
2ab50 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
2ab60 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
2ab70 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 **.** ^In the le
2ab80 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2ab90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
2aba0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 will be either
2abb0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a [SQLITE_BUSY],.*
2abc0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
2abd0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b [SQLITE_ROW], [
2abe0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f SQLITE_ERROR], o
2abf0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 r [SQLITE_MISUSE
2ac00 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
2ac10 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
2ac20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
2ac30 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
2ac40 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
2ac50 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
2ac60 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
2ac70 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e as well..**.** ^
2ac80 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 [SQLITE_BUSY] me
2ac90 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 ans that the dat
2aca0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 abase engine was
2acb0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 unable to acqui
2acc0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 re the.** databa
2acd0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 se locks it need
2ace0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e s to do its job.
2acf0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d ^If the statem
2ad00 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 ent is a [COMMIT
2ad10 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f ].** or occurs o
2ad20 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 utside of an exp
2ad30 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
2ad40 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 n, then you can
2ad50 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 retry the.** sta
2ad60 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 tement. If the
2ad70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
2ad80 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 a [COMMIT] and
2ad90 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e occurs within an
2ada0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 .** explicit tra
2adb0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f nsaction then yo
2adc0 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 u should rollbac
2add0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
2ade0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 n before.** cont
2adf0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b inuing..**.** ^[
2ae00 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
2ae10 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
2ae20 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
2ae30 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
2ae40 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
2ae50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
2ae60 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
2ae70 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
2ae80 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
2ae90 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
2aea0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
2aeb0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
2aec0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
2aed0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
2aee0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
2aef0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 state..**.** ^If
2af00 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2af10 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 nt being execute
2af20 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 d returns any da
2af30 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 ta, then [SQLITE
2af40 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 _ROW].** is retu
2af50 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 rned each time a
2af60 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 new row of data
2af70 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 is ready for pr
2af80 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a ocessing by the.
2af90 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 ** caller. The v
2afa0 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 alues may be acc
2afb0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 essed using the
2afc0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
2afd0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 unctions]..** sq
2afe0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 lite3_step() is
2aff0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 called again to
2b000 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 retrieve the nex
2b010 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a t row of data..*
2b020 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 *.** ^[SQLITE_ER
2b030 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
2b040 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
2b050 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
2b060 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
2b070 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
2b080 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
2b090 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
2b0a0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
2b0b0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
2b0c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
2b0d0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
2b0e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
2b0f0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 rmsg()]..** ^Wit
2b100 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
2b110 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
2b120 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
2b130 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
2b140 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
2b150 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
2b160 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
2b170 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
2b180 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
2b190 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
2b1a0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2b1b0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
2b1c0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2b1d0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 tement]. ^In th
2b1e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2b1f0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 ,.** the more sp
2b200 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
2b210 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 e is returned di
2b220 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 rectly by sqlite
2b230 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_step()..**.**
2b240 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2b250 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 means that the t
2b260 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 his routine was
2b270 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 called inappropr
2b280 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 iately..** Perha
2b290 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 ps it was called
2b2a0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
2b2b0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2b2c0 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 has.** already b
2b2d0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e een [sqlite3_fin
2b2e0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
2b2f0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 d] or on one tha
2b300 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 t had.** previou
2b310 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 sly returned [SQ
2b320 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b LITE_ERROR] or [
2b330 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f SQLITE_DONE]. O
2b340 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 r it could.** be
2b350 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
2b360 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
2b370 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 connection is b
2b380 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f eing used by two
2b390 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 or.** more thre
2b3a0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
2b3b0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a moment in time..
2b3c0 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 **.** For all ve
2b3d0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2b3e0 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 up to and inclu
2b3f0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 ding 3.6.23.1, a
2b400 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
2b410 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 ite3_reset()] wa
2b420 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 s required after
2b430 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2b440 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e returned anythin
2b450 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 g.** other than
2b460 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 [SQLITE_ROW] bef
2b470 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 ore any subseque
2b480 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 nt invocation of
2b490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
2b4a0 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 (). Failure to
2b4b0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
2b4c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
2b4d0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
2b4e0 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 reset()] would r
2b4f0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c esult in an [SQL
2b500 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 ITE_MISUSE] retu
2b510 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 rn from.** sqlit
2b520 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 e3_step(). But
2b530 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e after version 3.
2b540 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 6.23.1, sqlite3_
2b550 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 step() began.**
2b560 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
2b570 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 _reset()] automa
2b580 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 tically in this
2b590 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 circumstance rat
2b5a0 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 her.** than retu
2b5b0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 rning [SQLITE_MI
2b5c0 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 SUSE]. This is
2b5d0 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 not considered a
2b5e0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a compatibility.*
2b5f0 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 * break because
2b600 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 any application
2b610 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 that ever receiv
2b620 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 es an SQLITE_MIS
2b630 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 USE error.** is
2b640 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 broken by defini
2b650 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 tion. The [SQLI
2b660 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 TE_OMIT_AUTORESE
2b670 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
2b680 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 option.** can be
2b690 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 used to restore
2b6a0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 the legacy beha
2b6b0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 vior..**.** <b>G
2b6c0 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 oofy Interface A
2b6d0 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 lert:</b> In the
2b6e0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
2b6f0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 e, the sqlite3_s
2b700 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 tep().** API alw
2b710 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
2b720 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
2b730 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
2b740 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a , following any.
2b750 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ** error other t
2b760 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
2b770 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 ] and [SQLITE_MI
2b780 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 SUSE]. You must
2b790 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
2b7a0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2b7b0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2b7c0 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 )] in order to f
2b7d0 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a ind one of the.*
2b7e0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f * specific [erro
2b7f0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 r codes] that be
2b800 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 tter describes t
2b810 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 he error..** We
2b820 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 admit that this
2b830 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 is a goofy desig
2b840 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 n. The problem
2b850 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a has been fixed.*
2b860 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 * with the "v2"
2b870 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 interface. If y
2b880 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f ou prepare all o
2b890 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 f your SQL state
2b8a0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 ments.** using e
2b8b0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
2b8c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2b8d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2b8e0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 16_v2()] instead
2b8f0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 .** of the legac
2b900 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
2b910 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
2b920 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
2b930 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 interfaces,.** t
2b940 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 hen the more spe
2b950 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
2b960 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 es] are returned
2b970 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 directly.** by
2b980 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
2b990 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
2b9a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
2b9b0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a s recommended..*
2b9c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 /.int sqlite3_st
2b9d0 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ep(sqlite3_stmt*
2b9e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b9f0 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f EF: Number of co
2ba00 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c lumns in a resul
2ba10 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 t set.**.** ^The
2ba20 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2ba30 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 unt(P) interface
2ba40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2ba50 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
2ba60 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
2ba70 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 row of the resu
2ba80 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 lt set of [prepa
2ba90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
2baa0 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 ..** ^If prepare
2bab0 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f d statement P do
2bac0 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 es not have resu
2bad0 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 lts ready to ret
2bae0 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c urn.** (via call
2baf0 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 s to the [sqlite
2bb00 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 3_column_int | s
2bb10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 qlite3_column_*(
2bb20 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 )] of.** interfa
2bb30 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 ces) then sqlite
2bb40 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 3_data_count(P)
2bb50 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 returns 0..** ^T
2bb60 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2bb70 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 count(P) routine
2bb80 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 also returns 0
2bb90 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 if P is a NULL p
2bba0 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 ointer..** ^The
2bbb0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
2bbc0 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 nt(P) routine re
2bbd0 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 turns 0 if the p
2bbe0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a revious call to.
2bbf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
2bc00 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 ](P) returned [S
2bc10 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 QLITE_DONE]. ^T
2bc20 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2bc30 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c count(P).** will
2bc40 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f return non-zero
2bc50 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c if previous cal
2bc60 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 l to [sqlite3_st
2bc70 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a ep](P) returned.
2bc80 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ** [SQLITE_ROW],
2bc90 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 except in the c
2bca0 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 ase of the [PRAG
2bcb0 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 MA incremental_v
2bcc0 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 acuum].** where
2bcd0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
2bce0 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 s zero since eac
2bcf0 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d h step of that m
2bd00 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 ulti-step.** pra
2bd10 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f gma returns 0 co
2bd20 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a lumns of data..*
2bd30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2bd40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2bd50 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 ount()].*/.int s
2bd60 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2bd70 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
2bd80 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
2bd90 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 API3REF: Fundame
2bda0 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a ntal Datatypes.*
2bdb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
2bdc0 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 TE_TEXT.**.** ^(
2bdd0 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 Every value in S
2bde0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 QLite has one of
2bdf0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 five fundamenta
2be00 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a l datatypes:.**.
2be10 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
2be20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
2be30 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 teger.** <li> 64
2be40 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 -bit IEEE floati
2be50 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a ng point number.
2be60 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a ** <li> string.*
2be70 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c * <li> BLOB.** <
2be80 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c li> NULL.** </ul
2be90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 >)^.**.** These
2bea0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f constants are co
2beb0 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 des for each of
2bec0 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a those types..**.
2bed0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 ** Note that the
2bee0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e SQLITE_TEXT con
2bef0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 stant was also u
2bf00 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 sed in SQLite ve
2bf10 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 rsion 2.** for a
2bf20 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 completely diff
2bf30 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 erent meaning.
2bf40 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 Software that li
2bf50 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 nks against both
2bf60 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
2bf70 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 on 2 and SQLite
2bf80 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 version 3 should
2bf90 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 use SQLITE3_TEX
2bfa0 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 T, not.** SQLITE
2bfb0 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e _TEXT..*/.#defin
2bfc0 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 e SQLITE_INTEGER
2bfd0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 1.#define SQLI
2bfe0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 TE_FLOAT 2.#d
2bff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f efine SQLITE_BLO
2c000 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 B 4.#define
2c010 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 SQLITE_NULL
2c020 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 5.#ifdef SQLITE_
2c030 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c TEXT.# undef SQL
2c040 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 ITE_TEXT.#else.#
2c050 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 define SQLITE_T
2c060 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 EXT 3.#endif
2c070 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
2c080 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a _TEXT 3../*.
2c090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
2c0a0 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 ult Values From
2c0b0 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f A Query.** KEYWO
2c0c0 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 RDS: {column acc
2c0d0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a ess functions}.*
2c0e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
2c0f0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 nes form the "re
2c100 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 sult set" interf
2c110 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ace..**.** ^Thes
2c120 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
2c130 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 n information ab
2c140 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c out a single col
2c150 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 umn of the curre
2c160 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 nt.** result row
2c170 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 of a query. ^I
2c180 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 n every case the
2c190 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
2c1a0 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 is a pointer.**
2c1b0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
2c1c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
2c1d0 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 is being evalua
2c1e0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 ted (the [sqlite
2c1f0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 3_stmt*].** that
2c200 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 was returned fr
2c210 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 om [sqlite3_prep
2c220 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 are_v2()] or one
2c230 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 of its variants
2c240 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 ).** and the sec
2c250 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
2c260 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
2c270 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 column for whic
2c280 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a h information.**
2c290 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 should be retur
2c2a0 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f ned. ^The leftmo
2c2b0 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 st column of the
2c2c0 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 result set has
2c2d0 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 the index 0..**
2c2e0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 ^The number of c
2c2f0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
2c300 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 sult can be dete
2c310 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 rmined using.**
2c320 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2c330 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 count()]..**.**
2c340 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2c350 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 ment does not cu
2c360 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f rrently point to
2c370 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 a valid row, or
2c380 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d if the.** colum
2c390 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f n index is out o
2c3a0 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 f range, the res
2c3b0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ult is undefined
2c3c0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
2c3d0 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 nes may only be
2c3e0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 called when the
2c3f0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c most recent call
2c400 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
2c410 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 step()] has retu
2c420 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 rned [SQLITE_ROW
2c430 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a ] and neither.**
2c440 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2c450 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f )] nor [sqlite3_
2c460 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 finalize()] have
2c470 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 been called sub
2c480 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 sequently..** If
2c490 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
2c4a0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 utines are calle
2c4b0 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
2c4c0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
2c4d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2c4e0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 e()] or after [s
2c4f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
2c500 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 as returned.** s
2c510 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 omething other t
2c520 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d han [SQLITE_ROW]
2c530 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
2c540 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 e undefined..**
2c550 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 If [sqlite3_step
2c560 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2c570 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c reset()] or [sql
2c580 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
2c590 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 .** are called f
2c5a0 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 rom a different
2c5b0 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 thread while any
2c5c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e of these routin
2c5d0 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e es.** are pendin
2c5e0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 g, then the resu
2c5f0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
2c600 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
2c610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
2c620 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
2c630 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 rns the.** [SQLI
2c640 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
2c650 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 atype code] for
2c660 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 the initial data
2c670 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 type.** of the
2c680 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 result column.
2c690 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 ^The returned va
2c6a0 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 lue is one of [S
2c6b0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a QLITE_INTEGER],.
2c6c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 ** [SQLITE_FLOAT
2c6d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d ], [SQLITE_TEXT]
2c6e0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c , [SQLITE_BLOB],
2c6f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c or [SQLITE_NULL
2c700 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a ]. The value.**
2c710 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2c720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
2c730 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 () is only meani
2c740 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 ngful if no type
2c750 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 .** conversions
2c760 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 have occurred as
2c770 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 described below
2c780 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 . After a type
2c790 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 conversion,.** t
2c7a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
2c7b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2c7c0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e umn_type() is un
2c7d0 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 defined. Future
2c7e0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 .** versions of
2c7f0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 SQLite may chang
2c800 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f e the behavior o
2c810 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e f sqlite3_column
2c820 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f _type().** follo
2c830 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 wing a type conv
2c840 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ersion..**.** ^I
2c850 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2c860 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 a BLOB or UTF-8
2c870 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
2c880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c890 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e ytes().** routin
2c8a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
2c8b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
2c8c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 that BLOB or st
2c8d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
2c8e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 result is a UTF
2c8f0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e -16 string, then
2c900 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c910 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 bytes() converts
2c920 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 .** the string t
2c930 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e o UTF-8 and then
2c940 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2c950 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
2c960 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
2c970 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
2c980 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
2c990 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 column_bytes() u
2c9a0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ses.** [sqlite3_
2c9b0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 snprintf()] to c
2c9c0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 onvert that valu
2c9d0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 e to a UTF-8 str
2c9e0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
2c9f0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2ca00 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
2ca10 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
2ca20 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
2ca30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2ca40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 olumn_bytes() re
2ca50 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2ca60 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2ca70 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
2ca80 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e F-16 string then
2ca90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c the sqlite3_col
2caa0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a umn_bytes16().**
2cab0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2cac0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2cad0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
2cae0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
2caf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2cb00 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 s a UTF-8 string
2cb10 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2cb20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2cb30 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 converts.** the
2cb40 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 string to UTF-16
2cb50 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e and then return
2cb60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
2cb70 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 bytes..** ^If th
2cb80 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 e result is a nu
2cb90 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e meric value then
2cba0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2cbb0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a bytes16() uses.*
2cbc0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
2cbd0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
2cbe0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
2cbf0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 a UTF-16 string
2cc00 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 and returns.** t
2cc10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2cc20 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e es in that strin
2cc30 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
2cc40 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 sult is NULL, th
2cc50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2cc60 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 n_bytes16() retu
2cc70 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
2cc80 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 ^The values retu
2cc90 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
2cca0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d _column_bytes()]
2ccb0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
2ccc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2ccd0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 ()] do not inclu
2cce0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d de the zero term
2ccf0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 inators at the e
2cd00 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 nd.** of the str
2cd10 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 ing. ^For clari
2cd20 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 ty: the values r
2cd30 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
2cd40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2cd50 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 tes()] and [sqli
2cd60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2cd70 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 16()] are the nu
2cd80 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 mber of.** bytes
2cd90 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 in the string,
2cda0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f not the number o
2cdb0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a f characters..**
2cdc0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 .** ^Strings ret
2cdd0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2cde0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 _column_text() a
2cdf0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2ce00 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 n_text16(),.** e
2ce10 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 ven empty string
2ce20 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 s, are always ze
2ce30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
2ce40 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 ^The return.** v
2ce50 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
2ce60 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 3_column_blob()
2ce70 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 for a zero-lengt
2ce80 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c h BLOB is a NULL
2ce90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
2cea0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 ^The object retu
2ceb0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
2cec0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
2ced0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f is an.** [unpro
2cee0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2cef0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 alue] object. A
2cf00 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
2cf10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2cf20 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ct.** may only b
2cf30 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c e used with [sql
2cf40 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
2cf50 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2cf60 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e result_value()].
2cf70 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 .** If the [unpr
2cf80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2cf90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 value] object re
2cfa0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
2cfb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
2cfc0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e ue()] is used in
2cfd0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 any other way,
2cfe0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a including calls.
2cff0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c ** to routines l
2d000 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c ike [sqlite3_val
2d010 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 ue_int()], [sqli
2d020 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
2d030 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 ],.** or [sqlite
2d040 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
2d050 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
2d060 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
2d070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
2d080 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 utines attempt t
2d090 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 o convert the va
2d0a0 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 lue where approp
2d0b0 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 riate. ^For.**
2d0c0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 example, if the
2d0d0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
2d0e0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 ntation is FLOAT
2d0f0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 and a text resu
2d100 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 lt.** is request
2d110 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 ed, [sqlite3_snp
2d120 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 rintf()] is used
2d130 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 internally to p
2d140 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f erform the.** co
2d150 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 nversion automat
2d160 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 ically. ^(The f
2d170 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 ollowing table d
2d180 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 etails the conve
2d190 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 rsions.** that a
2d1a0 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a re applied:.**.*
2d1b0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a * <blockquote>.*
2d1c0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d * <table border=
2d1d0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e "1">.** <tr><th>
2d1e0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 Internal<br>Typ
2d1f0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 e <th> Requested
2d200 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 <br>Type <th> C
2d210 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 onversion.**.**
2d220 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2d230 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2d240 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2d250 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
2d260 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f ULL <td> FLO
2d270 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c AT <td> Resul
2d280 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e t is 0.0.** <tr>
2d290 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
2d2a0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 d> TEXT <td
2d2b0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
2d2c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
2d2d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
2d2e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2d2f0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c > Result is NULL
2d300 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e pointer.** <tr>
2d310 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
2d320 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2d330 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 > Convert from i
2d340 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a nteger to float.
2d350 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
2d360 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 GER <td> TEXT
2d370 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
2d380 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
2d390 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c integer.** <tr><
2d3a0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
2d3b0 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
2d3c0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 Same as INTEGER
2d3d0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
2d3e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
2d3f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2d400 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f Convert from flo
2d410 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a at to integer.**
2d420 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2d430 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
2d440 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e <td> ASCII ren
2d450 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c dering of the fl
2d460 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 oat.** <tr><td>
2d470 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
2d480 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d BLOB <td> Sam
2d490 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 e as FLOAT->TEXT
2d4a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
2d4b0 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 XT <td> INTEG
2d4c0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 ER <td> Use at
2d4d0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
2d4e0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 TEXT <td>
2d4f0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 FLOAT <td> Us
2d500 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e e atof().** <tr>
2d510 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2d520 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2d530 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
2d540 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2d550 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2d560 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 <td> Convert to
2d570 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 TEXT then use at
2d580 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e oi().** <tr><td>
2d590 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 BLOB <td>
2d5a0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f FLOAT <td> Co
2d5b0 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 nvert to TEXT th
2d5c0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a en use atof().**
2d5d0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
2d5e0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 <td> TEXT
2d5f0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 <td> Add a zer
2d600 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 o terminator if
2d610 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c needed.** </tabl
2d620 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f e>.** </blockquo
2d630 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 te>)^.**.** The
2d640 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 table above make
2d650 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 s reference to s
2d660 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
2d670 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 y functions atoi
2d680 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 ().** and atof()
2d690 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e . SQLite does n
2d6a0 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 ot really use th
2d6b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
2d6c0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 It has its.** ow
2d6d0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 n equivalent int
2d6e0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 ernal routines.
2d6f0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 The atoi() and
2d700 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 atof() names are
2d710 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 .** used in the
2d720 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 table for brevit
2d730 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 y and because th
2d740 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 ey are familiar
2d750 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f to most.** C pro
2d760 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 grammers..**.**
2d770 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 Note that when t
2d780 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
2d790 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 occur, pointers
2d7a0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f returned by prio
2d7b0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 r.** calls to sq
2d7c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2d7d0 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c b(), sqlite3_col
2d7e0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f umn_text(), and/
2d7f0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f or.** sqlite3_co
2d800 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 lumn_text16() ma
2d810 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 y be invalidated
2d820 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 ..** Type conver
2d830 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 sions and pointe
2d840 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 r invalidations
2d850 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 might occur.** i
2d860 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 n the following
2d870 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c cases:.**.** <ul
2d880 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
2d890 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
2d8a0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 a BLOB and sqli
2d8b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2d8c0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
2d8d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2d8e0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 16() is called.
2d8f0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 A zero-terminat
2d900 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 or might.**
2d910 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 need to be adde
2d920 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e d to the string.
2d930 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
2d940 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
2d950 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 t is UTF-8 text
2d960 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
2d970 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a mn_bytes16() or.
2d980 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f ** sqlite3_
2d990 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
2d9a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 is called. The
2d9b0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 content must be
2d9c0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 converted.**
2d9d0 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 to UTF-16.</li
2d9e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e >.** <li> The in
2d9f0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 itial content is
2da00 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 UTF-16 text and
2da10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2da20 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 bytes() or.**
2da30 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
2da40 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c n_text() is call
2da50 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 ed. The content
2da60 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
2da70 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 ed.** to UT
2da80 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 F-8.</li>.** </u
2da90 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 l>.**.** ^Conver
2daa0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 sions between UT
2dab0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 F-16be and UTF-1
2dac0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6le are always d
2dad0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 one in place and
2dae0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c do.** not inval
2daf0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f idate a prior po
2db00 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 inter, though of
2db10 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 course the cont
2db20 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 ent of the buffe
2db30 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 r.** that the pr
2db40 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 ior pointer refe
2db50 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 rences will have
2db60 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 been modified.
2db70 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 Other kinds.**
2db80 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 of conversion ar
2db90 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 e done in place
2dba0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 when it is possi
2dbb0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d ble, but sometim
2dbc0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e es they.** are n
2dbd0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 ot possible and
2dbe0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 in those cases p
2dbf0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 rior pointers ar
2dc00 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a e invalidated..*
2dc10 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 *.** The safest
2dc20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 and easiest to r
2dc30 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 emember policy i
2dc40 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 s to invoke thes
2dc50 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e e routines.** in
2dc60 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
2dc70 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a owing ways:.**.*
2dc80 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 * <ul>.** <li>s
2dc90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2dca0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 xt() followed by
2dcb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2dcc0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
2dcd0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2dce0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f umn_blob() follo
2dcf0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
2dd00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
2dd10 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
2dd20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2dd30 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
2dd40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2dd50 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 tes16()</li>.**
2dd60 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f </ul>.**.** In o
2dd70 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 ther words, you
2dd80 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 should call sqli
2dd90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2dda0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f ),.** sqlite3_co
2ddb0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 lumn_blob(), or
2ddc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ddd0 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f ext16() first to
2dde0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c force the resul
2ddf0 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 t.** into the de
2de00 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 sired format, th
2de10 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 en invoke sqlite
2de20 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2de30 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
2de40 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2de50 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 to find the size
2de60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 of the result.
2de70 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c Do not mix call
2de80 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f s.** to sqlite3_
2de90 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 column_text() or
2dea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2deb0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c blob() with call
2dec0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
2ded0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2dee0 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 , and do not mix
2def0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
2df00 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2df10 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 ).** with calls
2df20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
2df30 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a n_bytes()..**.**
2df40 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 ^The pointers r
2df50 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 eturned are vali
2df60 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 d until a type c
2df70 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
2df80 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 as.** described
2df90 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c above, or until
2dfa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2dfb0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
2dfc0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
2dfd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2dfe0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 ] is called. ^T
2dff0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 he memory space
2e000 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 used to hold str
2e010 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 ings.** and BLOB
2e020 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d s is freed autom
2e030 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 atically. Do <b
2e040 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 >not</b> pass th
2e050 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
2e060 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ned.** [sqlite3_
2e070 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 column_blob()],
2e080 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2e090 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e text()], etc. in
2e0a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
2e0b0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ree()]..**.** ^(
2e0c0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f If a memory allo
2e0d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 cation error occ
2e0e0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 urs during the e
2e0f0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 valuation of any
2e100 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 .** of these rou
2e110 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 tines, a default
2e120 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e value is return
2e130 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 ed. The default
2e140 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 value.** is eit
2e150 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 her the integer
2e160 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 0, the floating
2e170 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 point number 0.0
2e180 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 , or a NULL.** p
2e190 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 ointer. Subsequ
2e1a0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
2e1b0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
2e1c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 will return.**
2e1d0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 [SQLITE_NOMEM].)
2e1e0 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ^.*/.const void
2e1f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2e200 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d blob(sqlite3_stm
2e210 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 t*, int iCol);.i
2e220 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nt sqlite3_colum
2e230 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f n_bytes(sqlite3_
2e240 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2e250 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
2e260 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c lumn_bytes16(sql
2e270 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2e280 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 iCol);.double sq
2e290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
2e2a0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
2e2b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
2e2c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2e2d0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
2e2e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
2e2f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
2e300 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 ite3_column_int6
2e310 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2e320 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 int iCol);.cons
2e330 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
2e340 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2e350 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
2e360 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 t*, int iCol);.c
2e370 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
2e380 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2e390 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2e3a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 int iCol);.int s
2e3b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2e3c0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a pe(sqlite3_stmt*
2e3d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c , int iCol);.sql
2e3e0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 ite3_value *sqli
2e3f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
2e400 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2e410 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a int iCol);../*.*
2e420 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 * CAPI3REF: Dest
2e430 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 roy A Prepared S
2e440 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
2e450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2e460 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 e3_finalize() fu
2e470 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 nction is called
2e480 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 to delete a [pr
2e490 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e4a0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f ]..** ^If the mo
2e4b0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 st recent evalua
2e4c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 tion of the stat
2e4d0 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 ement encountere
2e4e0 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f d no errors.** o
2e4f0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 r if the stateme
2e500 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e nt is never been
2e510 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e evaluated, then
2e520 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2e530 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 e() returns.** S
2e540 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 QLITE_OK. ^If t
2e550 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
2e560 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 valuation of sta
2e570 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c tement S failed,
2e580 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
2e590 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 _finalize(S) ret
2e5a0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 urns the appropr
2e5b0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
2e5c0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2e5d0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a d error code]..*
2e5e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2e5f0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 3_finalize(S) ro
2e600 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c utine can be cal
2e610 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 led at any point
2e620 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c during.** the l
2e630 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 ife cycle of [pr
2e640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e650 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 ] S:.** before s
2e660 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 tatement S is ev
2e670 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 er evaluated, af
2e680 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f ter.** one or mo
2e690 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c re calls to [sql
2e6a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f ite3_reset()], o
2e6b0 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c r after any call
2e6c0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
2e6d0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 step()] regardle
2e6e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
2e6f0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 not the stateme
2e700 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 nt has.** comple
2e710 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a ted execution..*
2e720 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 *.** ^Invoking s
2e730 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2e740 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) on a NULL poin
2e750 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 ter is a harmles
2e760 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 s no-op..**.** T
2e770 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
2e780 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 ust finalize eve
2e790 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ry [prepared sta
2e7a0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 tement] in order
2e7b0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 to avoid.** res
2e7c0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 ource leaks. It
2e7d0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 is a grievous e
2e7e0 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 rror for the app
2e7f0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 lication to try
2e800 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 to use.** a prep
2e810 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
2e820 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
2e830 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 finalized. Any
2e840 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 use of a prepar
2e850 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
2e860 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
2e870 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 n finalized can
2e880 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
2e890 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 ned and.** undes
2e8a0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 irable behavior
2e8b0 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 such as segfault
2e8c0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 s and heap corru
2e8d0 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ption..*/.int sq
2e8e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 lite3_finalize(s
2e8f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2e900 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2e910 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 3REF: Reset A Pr
2e920 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2e930 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
2e940 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 e sqlite3_reset(
2e950 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
2e960 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 lled to reset a
2e970 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e980 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 ent].** object b
2e990 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
2e9a0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 al state, ready
2e9b0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 to be re-execute
2e9c0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 d..** ^Any SQL s
2e9d0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c tatement variabl
2e9e0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 es that had valu
2e9f0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d es bound to them
2ea00 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 using.** the [s
2ea10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2ea20 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f | sqlite3_bind_
2ea30 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 *() API] retain
2ea40 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a their values..**
2ea50 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c Use [sqlite3_cl
2ea60 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 ear_bindings()]
2ea70 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e to reset the bin
2ea80 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 dings..**.** ^Th
2ea90 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
2eaa0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (S)] interface r
2eab0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 esets the [prepa
2eac0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
2ead0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 .** back to the
2eae0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 beginning of its
2eaf0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 program..**.**
2eb00 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
2eb10 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
2eb20 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
2eb30 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
2eb40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2eb50 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
2eb60 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 _ROW] or [SQLITE
2eb70 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 _DONE],.** or if
2eb80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
2eb90 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 )] has never bef
2eba0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ore been called
2ebb0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 on S,.** then [s
2ebc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2ebd0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
2ebe0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 _OK]..**.** ^If
2ebf0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2ec00 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2ec10 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
2ec20 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2ec30 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 tatement] S indi
2ec40 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 cated an error,
2ec50 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 then.** [sqlite3
2ec60 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
2ec70 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 ns an appropriat
2ec80 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a e [error code]..
2ec90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
2eca0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
2ecb0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
2ecc0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
2ecd0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 es.** of any [sq
2ece0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2ecf0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 bindings] on the
2ed00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2ed10 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 ment] S..*/.int
2ed20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 sqlite3_reset(sq
2ed30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2ed40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2ed50 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 REF: Create Or R
2ed60 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 edefine SQL Func
2ed70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 tions.** KEYWORD
2ed80 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 S: {function cre
2ed90 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a ation routines}.
2eda0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
2edb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2edc0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a d SQL function}.
2edd0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 ** KEYWORDS: {ap
2ede0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2edf0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d d SQL functions}
2ee00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
2ee10 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 nctions (collect
2ee20 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 ively known as "
2ee30 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
2ee40 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 n routines").**
2ee50 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
2ee60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
2ee70 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 aggregates or t
2ee80 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 o redefine the b
2ee90 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 ehavior.** of ex
2eea0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 isting SQL funct
2eeb0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
2eec0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 es. The only di
2eed0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 fferences betwee
2eee0 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 n.** these routi
2eef0 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 nes are the text
2ef00 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 encoding expect
2ef10 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 ed for.** the se
2ef20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 cond parameter (
2ef30 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2ef40 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 function being c
2ef50 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 reated).** and t
2ef60 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 he presence or a
2ef70 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 bsence of a dest
2ef80 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 ructor callback
2ef90 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 for.** the appli
2efa0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
2efb0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
2efc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
2efd0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 is the [database
2efe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 connection] to
2eff0 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a which the SQL.**
2f000 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 function is to
2f010 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 be added. ^If a
2f020 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
2f030 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 es more than one
2f040 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
2f050 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 nection then app
2f060 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2f070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d SQL functions m
2f080 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 ust be added.**
2f090 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
2f0a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 connection sepa
2f0b0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rately..**.** ^T
2f0c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
2f0d0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
2f0e0 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 of the SQL funct
2f0f0 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 ion to be create
2f100 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 d or.** redefine
2f110 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 d. ^The length
2f120 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c of the name is l
2f130 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 imited to 255 by
2f140 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a tes in a UTF-8.*
2f150 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e * representation
2f160 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 , exclusive of t
2f170 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
2f180 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 or. ^Note that
2f190 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 the name.** leng
2f1a0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 th limit is in U
2f1b0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 TF-8 bytes, not
2f1c0 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 characters nor U
2f1d0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a TF-16 bytes. .*
2f1e0 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 * ^Any attempt t
2f1f0 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 o create a funct
2f200 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 ion with a longe
2f210 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 r name.** will r
2f220 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 esult in [SQLITE
2f230 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 _MISUSE] being r
2f240 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
2f250 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
2f260 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 ter (nArg).** is
2f270 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
2f280 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 rguments that th
2f290 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
2f2a0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 r.** aggregate t
2f2b0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 akes. ^If this p
2f2c0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 arameter is -1,
2f2d0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e then the SQL fun
2f2e0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
2f2f0 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 egate may take a
2f300 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 ny number of arg
2f310 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 uments between 0
2f320 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a and the limit.*
2f330 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 * set by [sqlite
2f340 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 3_limit]([SQLITE
2f350 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
2f360 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 ARG]). If the t
2f370 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
2f380 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d r is less than -
2f390 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 1 or greater tha
2f3a0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 n 127 then the b
2f3b0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e ehavior is.** un
2f3c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
2f3d0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
2f3e0 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 eter, eTextRep,
2f3f0 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a specifies what.*
2f400 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c * [SQLITE_UTF8 |
2f410 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 text encoding]
2f420 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f this SQL functio
2f430 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a n prefers for.**
2f440 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e its parameters.
2f450 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 Every SQL func
2f460 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
2f470 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 ion must be able
2f480 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 to work.** with
2f490 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 UTF-8, UTF-16le
2f4a0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 , or UTF-16be.
2f4b0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 But some impleme
2f4c0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a ntations may be.
2f4d0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e ** more efficien
2f4e0 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 t with one encod
2f4f0 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 ing than another
2f500 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 . ^An applicati
2f510 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 on may.** invoke
2f520 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2f530 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 function() or sq
2f540 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
2f550 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 ction16() multip
2f560 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 le.** times with
2f570 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2f580 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 on but with diff
2f590 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 erent values of
2f5a0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 eTextRep..** ^Wh
2f5b0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c en multiple impl
2f5c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 ementations of t
2f5d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
2f5e0 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 are available,
2f5f0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 SQLite.** will p
2f600 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 ick the one that
2f610 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 involves the le
2f620 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 ast amount of da
2f630 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a ta conversion..*
2f640 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e * If there is on
2f650 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c ly a single impl
2f660 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 ementation which
2f670 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 does not care w
2f680 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f hat text.** enco
2f690 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 ding is used, th
2f6a0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 en the fourth ar
2f6b0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
2f6c0 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a [SQLITE_ANY]..*
2f6d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 *.** ^(The fifth
2f6e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
2f6f0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 arbitrary point
2f700 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 er. The impleme
2f710 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ntation of the.*
2f720 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 * function can g
2f730 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 ain access to th
2f740 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 is pointer using
2f750 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
2f760 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ata()].)^.**.**
2f770 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 ^The sixth, seve
2f780 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 nth and eighth p
2f790 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 arameters, xFunc
2f7a0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e , xStep and xFin
2f7b0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 al, are.** point
2f7c0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 ers to C-languag
2f7d0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 e functions that
2f7e0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
2f7f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
2f800 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 * aggregate. ^A
2f810 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
2f820 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
2f830 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
2f840 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 f the xFunc.** c
2f850 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 allback only; NU
2f860 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 LL pointers must
2f870 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
2f880 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e e xStep and xFin
2f890 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 al.** parameters
2f8a0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 . ^An aggregate
2f8b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
2f8c0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
2f8d0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 ntation of xStep
2f8e0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 .** and xFinal a
2f8f0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 nd NULL pointer
2f900 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 must be passed f
2f910 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 or xFunc. ^To de
2f920 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 lete an existing
2f930 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
2f940 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 or aggregate, p
2f950 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ass NULL pointer
2f960 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 s for all three
2f970 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c function.** call
2f980 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 backs..**.** ^(I
2f990 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 f the ninth para
2f9a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2f9b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2f9c0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c _v2() is not NUL
2f9d0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 L,.** then it is
2f9e0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 destructor for
2f9f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
2fa00 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a data pointer. .*
2fa10 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 * The destructor
2fa20 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
2fa30 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
2fa40 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 deleted, either
2fa50 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 by being.** ove
2fa60 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 rloaded or when
2fa70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2fa80 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 nection closes.)
2fa90 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 ^.** ^The destru
2faa0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 ctor is also inv
2fab0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c oked if the call
2fac0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
2fad0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
2fae0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 2() fails..** ^W
2faf0 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 hen the destruct
2fb00 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 or callback of t
2fb10 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 he tenth paramet
2fb20 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 er is invoked, i
2fb30 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 t.** is passed a
2fb40 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
2fb50 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 which is a copy
2fb60 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
2fb70 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 ion data .** poi
2fb80 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 nter which was t
2fb90 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
2fba0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 er to sqlite3_cr
2fbb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
2fbc0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ()..**.** ^It is
2fbd0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 permitted to re
2fbe0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 gister multiple
2fbf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
2fc00 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 of the same.** f
2fc10 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 unctions with th
2fc20 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 e same name but
2fc30 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 with either diff
2fc40 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 ering numbers of
2fc50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 .** arguments or
2fc60 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 differing prefe
2fc70 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
2fc80 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 ngs. ^SQLite wi
2fc90 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d ll use.** the im
2fca0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 plementation tha
2fcb0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d t most closely m
2fcc0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 atches the way i
2fcd0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 n which the.** S
2fce0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 QL function is u
2fcf0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f sed. ^A functio
2fd00 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
2fd10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 with a non-nega
2fd20 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 tive.** nArg par
2fd30 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 ameter is a bett
2fd40 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
2fd50 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
2fd60 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 ntation with.**
2fd70 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e a negative nArg.
2fd80 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 ^A function wh
2fd90 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 ere the preferre
2fda0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a d text encoding.
2fdb0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 ** matches the d
2fdc0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 atabase encoding
2fdd0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 is a better.**
2fde0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
2fdf0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
2fe00 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 encoding is diff
2fe10 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 erent. .** ^A f
2fe20 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
2fe30 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
2fe40 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e rence is between
2fe50 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 UTF16le and UTF
2fe60 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 16be.** is a clo
2fe70 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ser match than a
2fe80 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
2fe90 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
2fea0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 ference is.** be
2feb0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 tween UTF8 and U
2fec0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 TF16..**.** ^Bui
2fed0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 lt-in functions
2fee0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 may be overloade
2fef0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 d by new applica
2ff00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
2ff10 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 ctions..**.** ^A
2ff20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
2ff30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
2ff40 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 s permitted to c
2ff50 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c all other.** SQL
2ff60 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 ite interfaces.
2ff70 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 However, such c
2ff80 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a alls must not.**
2ff90 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
2ffa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e ase connection n
2ffb0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 or finalize or r
2ffc0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
2ffd0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 d.** statement i
2ffe0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 n which the func
2fff0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
30000 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
30010 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
30020 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
30030 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
30040 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
30050 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
30060 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
30070 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
30080 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
30090 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
300a0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
300b0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
300c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
300d0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
300e0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
300f0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
30100 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 ntext*).);.int s
30110 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
30120 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 nction16(. sqli
30130 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
30140 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e void *zFunction
30150 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
30160 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
30170 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
30180 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
30190 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
301a0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
301b0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
301c0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
301d0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
301e0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
301f0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
30200 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
30210 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
30220 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
30230 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
30240 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
30250 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
30260 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
30270 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
30280 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
30290 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
302a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
302b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
302c0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
302d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
302e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
302f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
30300 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
30310 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f _context*),. vo
30320 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f id(*xDestroy)(vo
30330 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
30340 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e API3REF: Text En
30350 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 codings.**.** Th
30360 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 ese constant def
30370 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
30380 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 s that represent
30390 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 the various.**
303a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 text encodings s
303b0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
303c0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
303d0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 QLITE_UTF8
303e0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
303f0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 QLITE_UTF16LE
30400 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
30410 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 QLITE_UTF16BE
30420 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
30430 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 QLITE_UTF16
30440 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 4 /* Use
30450 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
30460 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 er */.#define SQ
30470 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 LITE_ANY
30480 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 5 /* sqli
30490 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
304a0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 ion only */.#def
304b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 ine SQLITE_UTF16
304c0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f _ALIGNED 8 /
304d0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
304e0 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 _collation only
304f0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
30500 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
30510 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
30520 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
30530 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
30540 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
30550 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
30560 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
30570 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
30580 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
30590 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
305a0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
305b0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
305c0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
305d0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
305e0 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
305f0 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
30600 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 ions. To help e
30610 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 ncourage people
30620 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e to avoid.** usin
30630 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e g these function
30640 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f s, we are not go
30650 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 ing to tell you
30660 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f what they do..*/
30670 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
30680 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a OMIT_DEPRECATED.
30690 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
306a0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 D int sqlite3_ag
306b0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 gregate_count(sq
306c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
306d0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
306e0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 ED int sqlite3_e
306f0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 xpired(sqlite3_s
30700 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 tmt*);.SQLITE_DE
30710 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
30720 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 ite3_transfer_bi
30730 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 ndings(sqlite3_s
30740 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 tmt*, sqlite3_st
30750 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 mt*);.SQLITE_DEP
30760 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
30770 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 te3_global_recov
30780 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 er(void);.SQLITE
30790 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 _DEPRECATED void
307a0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f sqlite3_thread_
307b0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 cleanup(void);.S
307c0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
307d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d int sqlite3_mem
307e0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a ory_alarm(void(*
307f0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f )(void*,sqlite3_
30800 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 int64,int),.
30810 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
30820 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f void*,sqlite3_
30830 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a int64);.#endif..
30840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
30850 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 Obtaining SQL Fu
30860 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 nction Parameter
30870 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 Values.**.** Th
30880 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 e C-language imp
30890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 lementation of S
308a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 QL functions and
308b0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 aggregates uses
308c0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 .** this set of
308d0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e interface routin
308e0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 es to access the
308f0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 parameter value
30900 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 s on.** the func
30910 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 tion or aggregat
30920 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 e..**.** The xFu
30930 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 nc (for scalar f
30940 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 unctions) or xSt
30950 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 ep (for aggregat
30960 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a es) parameters.*
30970 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
30980 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
30990 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
309a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
309b0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c )].** define cal
309c0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c lbacks that impl
309d0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 ement the SQL fu
309e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
309f0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 egates..** The 3
30a00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
30a10 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 these callbacks
30a20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
30a30 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 ointers to.** [p
30a40 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
30a50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
30a60 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b There is one [
30a70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
30a80 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 bject for.** eac
30a90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
30aa0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e he SQL function.
30ab0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
30ac0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 are used to.**
30ad0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 extract values f
30ae0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
30af0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
30b00 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
30b10 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 tines work only
30b20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 with [protected
30b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
30b40 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 bjects..** Any a
30b50 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
30b60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 ese routines on
30b70 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 an [unprotected
30b80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a sqlite3_value].*
30b90 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 * object results
30ba0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
30bb0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 havior..**.** ^T
30bc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f hese routines wo
30bd0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 rk just like the
30be0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b corresponding [
30bf0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
30c00 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 nctions].** exce
30c10 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 pt that these r
30c20 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
30c30 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
30c40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
30c50 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
30c60 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
30c70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
30c80 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
30c90 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
30ca0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
30cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
30cc0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
30cd0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
30ce0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
30cf0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
30d00 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
30d10 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 t machine. ^The
30d20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
30d30 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
30d40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
30d50 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
30d60 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
30d70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
30d80 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
30d90 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
30da0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
30db0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
30dc0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
30dd0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
30de0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
30df0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
30e00 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
30e10 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
30e20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
30e30 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
30e40 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
30e50 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
30e60 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
30e70 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
30e80 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
30e90 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
30ea0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
30eb0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
30ec0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
30ed0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
30ee0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
30ef0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
30f00 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
30f10 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
30f20 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
30f30 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
30f40 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
30f50 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
30f60 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
30f70 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 on is returned.)
30f80 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 ^.**.** Please p
30f90 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 ay particular at
30fa0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 tention to the f
30fb0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 act that the poi
30fc0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a nter returned.**
30fd0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
30fe0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
30ff0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
31000 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
31010 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
31020 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
31030 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
31040 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
31050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
31060 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
31070 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
31080 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 16()], [sqlite3_
31090 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
310a0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
310b0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a lue_text16()]..*
310c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
310d0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
310e0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
310f0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 thread as.** th
31100 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
31110 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 hat supplied the
31120 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
31130 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f ] parameters..*/
31140 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
31150 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
31160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
31170 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
31180 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
31190 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
311a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
311b0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
311c0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
311d0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
311e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
311f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
31200 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
31210 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
31220 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
31230 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
31240 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
31250 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
31260 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
31270 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
31280 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
31290 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
312a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
312b0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
312c0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
312d0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
312e0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
312f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
31300 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
31310 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
31320 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
31330 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
31340 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
31350 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
31360 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
31370 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
31380 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
31390 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
313a0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 n Context.**.**
313b0 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 Implementations
313c0 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c of aggregate SQL
313d0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 functions use t
313e0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 his.** routine t
313f0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
31400 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 y for storing th
31410 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a eir state..**.**
31420 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 ^The first time
31430 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 the sqlite3_agg
31440 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
31450 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 ,N) routine is c
31460 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 alled .** for a
31470 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 particular aggre
31480 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 gate function, S
31490 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 QLite.** allocat
314a0 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 es N of memory,
314b0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 zeroes out that
314c0 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 memory, and retu
314d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a rns a pointer.**
314e0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f to the new memo
314f0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 ry. ^On second a
31500 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 nd subsequent ca
31510 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
31520 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
31530 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 ext() for the sa
31540 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
31550 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a ction instance,.
31560 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 ** the same buff
31570 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
31580 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 Sqlite3_aggrega
31590 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 te_context() is
315a0 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c normally.** call
315b0 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
315c0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 invocation of t
315d0 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 he xStep callbac
315e0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a k and then one.*
315f0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e * last time when
31600 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c the xFinal call
31610 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e back is invoked.
31620 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 ^(When no rows
31630 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 match.** an agg
31640 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 regate query, th
31650 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 e xStep() callba
31660 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 ck of the aggreg
31670 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ate function.**
31680 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
31690 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 s never called a
316a0 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 nd xFinal() is c
316b0 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e alled exactly on
316c0 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 ce..** In those
316d0 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 cases, sqlite3_a
316e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
316f0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c () might be call
31700 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 ed for the.** fi
31710 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 rst time from wi
31720 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e thin xFinal().)^
31730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
31740 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
31750 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 ntext(C,N) routi
31760 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c ne returns a NUL
31770 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 L pointer .** wh
31780 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 en first called
31790 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 if N is less tha
317a0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
317b0 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 ro or if a memor
317c0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 y.** allocate er
317d0 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a ror occurs..**.*
317e0 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f * ^(The amount o
317f0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 f space allocate
31800 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 d by sqlite3_agg
31810 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
31820 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d ,N) is.** determ
31830 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 ined by the N pa
31840 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 rameter on first
31850 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
31860 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a . Changing the.
31870 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e ** value of N in
31880 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
31890 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 to sqlite3_aggr
318a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
318b0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 within.** the sa
318c0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
318d0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 ction instance w
318e0 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 ill not resize t
318f0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c he memory.** all
31900 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 ocation.)^ With
31910 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 in the xFinal ca
31920 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 llback, it is cu
31930 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a stomary to set.*
31940 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 * N=0 in calls t
31950 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 o sqlite3_aggreg
31960 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
31970 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 so that no .**
31980 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 pointless memory
31990 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 allocations occ
319a0 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ur..**.** ^SQLit
319b0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
319c0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 frees the memory
319d0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a allocated by .*
319e0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
319f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 ate_context() wh
31a00 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
31a10 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
31a20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
31a30 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
31a40 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
31a50 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
31a60 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
31a70 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
31a80 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
31a90 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
31aa0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 the xStep or xFi
31ab0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 nal callback rou
31ac0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
31ad0 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
31ae0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a te.** function..
31af0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
31b00 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
31b10 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
31b20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
31b30 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ** the aggregate
31b40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
31b50 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 running..*/.voi
31b60 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 d *sqlite3_aggre
31b70 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c gate_context(sql
31b80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
31b90 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a nt nBytes);../*.
31ba0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 ** CAPI3REF: Use
31bb0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 r Data For Funct
31bc0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ions.**.** ^The
31bd0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
31be0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
31bf0 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
31c00 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
31c10 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 hat was the pUse
31c20 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 rData parameter
31c30 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 (the 5th paramet
31c40 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
31c50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
31c60 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
31c70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
31c80 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
31c90 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
31ca0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
31cb0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
31cc0 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
31cd0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
31ce0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
31cf0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
31d00 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
31d10 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
31d20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
31d30 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
31d40 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
31d50 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
31d60 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
31d70 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
31d80 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
31d90 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 Connection For F
31da0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
31db0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 The sqlite3_cont
31dc0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 ext_db_handle()
31dd0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
31de0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
31df0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 he pointer to th
31e00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
31e10 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 ection] (the 1st
31e20 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
31e30 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
31e40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
31e50 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
31e60 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
31e70 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
31e80 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
31e90 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
31ea0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
31eb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
31ec0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 */.sqlite3 *sqli
31ed0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
31ee0 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
31ef0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
31f00 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
31f10 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
31f20 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c a.**.** The foll
31f30 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 owing two functi
31f40 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 ons may be used
31f50 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 by scalar SQL fu
31f60 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 nctions to.** as
31f70 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 sociate metadata
31f80 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 with argument v
31f90 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 alues. If the sa
31fa0 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 me value is pass
31fb0 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c ed to.** multipl
31fc0 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 e invocations of
31fd0 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 the same SQL fu
31fe0 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 nction during qu
31ff0 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 ery execution, u
32000 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 nder.** some cir
32010 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 cumstances the a
32020 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 ssociated metada
32030 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 ta may be preser
32040 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a ved. This may.**
32050 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 be used, for ex
32060 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 ample, to add a
32070 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 regular-expressi
32080 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c on matching scal
32090 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ar.** function.
320a0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
320b0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
320c0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 lar expression i
320d0 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d s stored as.** m
320e0 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 etadata associat
320f0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 ed with the SQL
32100 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
32110 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 the regular expr
32120 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 ession.** patter
32130 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 n. The compiled
32140 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
32150 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
32160 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
32170 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
32180 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
32190 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 n so that the or
321a0 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 iginal pattern s
321b0 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f tring.** does no
321c0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 t need to be rec
321d0 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 ompiled on each
321e0 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a invocation..**.*
321f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
32200 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
32210 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
32220 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
32230 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
32240 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 ciated by the sq
32250 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
32260 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 a() function wit
32270 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 h the Nth argume
32280 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 nt.** value to t
32290 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
322a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
322b0 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 ^If no metadata
322c0 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a has been ever.*
322d0 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 * been set for t
322e0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 he Nth argument
322f0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c of the function,
32300 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 or if the corre
32310 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 sponding.** func
32320 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 tion parameter h
32330 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 as changed since
32340 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 the meta-data w
32350 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 as set,.** then
32360 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
32370 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 ata() returns a
32380 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
32390 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
323a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _set_auxdata() i
323b0 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 nterface saves t
323c0 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 he metadata.** p
323d0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 ointed to by its
323e0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 3rd parameter a
323f0 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 s the metadata f
32400 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 or the N-th.** a
32410 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 rgument of the a
32420 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
32430 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 ed function. Su
32440 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c bsequent.** call
32450 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 s to sqlite3_get
32460 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 _auxdata() might
32470 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 return this dat
32480 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 a, if it has.**
32490 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 not been destroy
324a0 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 ed..** ^If it is
324b0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 not NULL, SQLit
324c0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 e will invoke th
324d0 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 e destructor.**
324e0 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 function given b
324f0 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 y the 4th parame
32500 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 ter to sqlite3_s
32510 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a et_auxdata() on.
32520 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 ** the metadata
32530 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 when the corresp
32540 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 onding function
32550 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 parameter change
32560 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 s.** or when the
32570 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 SQL statement c
32580 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 ompletes, whiche
32590 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e ver comes first.
325a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 .**.** SQLite is
325b0 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 free to call th
325c0 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 e destructor and
325d0 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f drop metadata o
325e0 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 n any.** paramet
325f0 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 er of any functi
32600 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 on at any time.
32610 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 ^The only guara
32620 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 ntee is that.**
32630 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 the destructor w
32640 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 ill be called be
32650 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 fore the metadat
32660 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a a is dropped..**
32670 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 .** ^(In practic
32680 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
32690 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
326a0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
326b0 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f for.** expressio
326c0 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 ns that are cons
326d0 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 tant at compile
326e0 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 time. This inclu
326f0 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 des literal.** v
32700 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d alues and [param
32710 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 eters].)^.**.**
32720 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
32730 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 ust be called fr
32740 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 om the same thre
32750 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 ad in which.** t
32760 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
32770 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 is running..*/.v
32780 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 oid *sqlite3_get
32790 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 _auxdata(sqlite3
327a0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e _context*, int N
327b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
327c0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 set_auxdata(sqli
327d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
327e0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 t N, void*, void
327f0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a (*)(void*));...
32800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32810 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 Constants Defini
32820 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 ng Special Destr
32830 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a uctor Behavior.*
32840 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 *.** These are s
32850 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f pecial values fo
32860 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 r the destructor
32870 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 that is passed
32880 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e in as the.** fin
32890 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 al argument to r
328a0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
328b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
328c0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 b()]. ^If the d
328d0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
328e0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
328f0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
32900 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
32910 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
32920 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
32930 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
32940 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
32950 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
32960 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 d. ^The.** SQLI
32970 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c TE_TRANSIENT val
32980 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ue means that th
32990 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c e content will l
329a0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a ikely change in.
329b0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 ** the near futu
329c0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 re and that SQLi
329d0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 te should make i
329e0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
329f0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
32a00 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 ntent before ret
32a10 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 urning..**.** Th
32a20 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 e typedef is nec
32a30 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 essary to work a
32a40 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 round problems i
32a50 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b n certain.** C++
32a60 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 compilers..*/.t
32a70 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 ypedef void (*sq
32a80 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
32a90 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 _type)(void*);.#
32aa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
32ab0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 ATIC ((sqli
32ac0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
32ad0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 ype)0).#define S
32ae0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 QLITE_TRANSIENT
32af0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
32b00 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a ructor_type)-1).
32b10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
32b20 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 Setting The Res
32b30 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 ult Of An SQL Fu
32b40 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 nction.**.** The
32b50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
32b60 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e used by the xFun
32b70 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c c or xFinal call
32b80 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d backs that.** im
32b90 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 plement SQL func
32ba0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
32bb0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 ates. See.** [s
32bc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
32bd0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 nction()] and [s
32be0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
32bf0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 nction16()].** f
32c00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
32c10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
32c20 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
32c30 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 work very much
32c40 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 like the [parame
32c50 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d ter binding] fam
32c60 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 ily of.** functi
32c70 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 ons used to bind
32c80 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 values to host
32c90 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 parameters in pr
32ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
32cb0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 s..** Refer to t
32cc0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 he [SQL paramete
32cd0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e r] documentation
32ce0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
32cf0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
32d00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
32d10 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e result_blob() in
32d20 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
32d30 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 result from.**
32d40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
32d50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
32d60 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 to be the BLOB w
32d70 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 hose content is
32d80 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 pointed.** to by
32d90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
32da0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 meter and which
32db0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 is N bytes long
32dc0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a where N is the.*
32dd0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 * third paramete
32de0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
32df0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
32e00 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 oblob() interfac
32e10 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c es set the resul
32e20 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
32e30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
32e40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
32e50 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 BLOB containing
32e60 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 all zero.** byt
32e70 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 es and N bytes i
32e80 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 n size, where N
32e90 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
32ea0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
32eb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
32ec0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 lite3_result_dou
32ed0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
32ee0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
32ef0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
32f00 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
32f10 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
32f20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
32f30 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a alue specified.*
32f40 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 * by its 2nd arg
32f50 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
32f60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
32f70 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
32f80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
32f90 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a r16() functions.
32fa0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 ** cause the imp
32fb0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e lemented SQL fun
32fc0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 ction to throw a
32fd0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 n exception..**
32fe0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 ^SQLite uses the
32ff0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 string pointed
33000 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 to by the.** 2nd
33010 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
33020 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33030 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f or() or sqlite3_
33040 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
33050 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 .** as the text
33060 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 of an error mess
33070 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e age. ^SQLite in
33080 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 terprets the err
33090 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 or.** message st
330a0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
330b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
330c0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 as UTF-8. ^SQLi
330d0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 te.** interprets
330e0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d the string from
330f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33100 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 error16() as UTF
33110 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a -16 in native.**
33120 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 byte order. ^I
33130 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
33140 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
33150 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
33160 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
33170 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
33180 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 s negative then
33190 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 SQLite takes as
331a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
331b0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 sage all text up
331c0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
331d0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
331e0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 r..** ^If the th
331f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
33200 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33210 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 error() or.** sq
33220 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
33230 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 or16() is non-ne
33240 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
33250 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 te takes that ma
33260 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 ny.** bytes (not
33270 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f characters) fro
33280 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
33290 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 ter as the error
332a0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 message..** ^Th
332b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
332c0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
332d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
332e0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 r16().** routine
332f0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 s make a private
33300 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 copy of the err
33310 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 or message text
33320 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 before.** they r
33330 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 eturn. Hence, t
33340 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
33350 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 ion can dealloca
33360 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 te or.** modify
33370 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 the text after t
33380 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f hey return witho
33390 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 ut harm..** ^The
333a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
333b0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e error_code() fun
333c0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 ction changes th
333d0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 e error code.**
333e0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 returned by SQLi
333f0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f te as a result o
33400 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 f an error in a
33410 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 function. ^By d
33420 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 efault,.** the e
33430 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c rror code is SQL
33440 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 ITE_ERROR. ^A s
33450 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
33460 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
33470 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 _error().** or s
33480 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
33490 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 ror16() resets t
334a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f he error code to
334b0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a SQLITE_ERROR..*
334c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
334d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 3_result_error_t
334e0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 oobig() interfac
334f0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
33500 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 to throw an.** e
33510 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 rror indicating
33520 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 that a string or
33530 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e BLOB is too lon
33540 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a g to represent..
33550 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
33560 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
33570 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 nomem() interfac
33580 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
33590 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 to throw an.** e
335a0 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 rror indicating
335b0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c that a memory al
335c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e location failed.
335d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
335e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 te3_result_int()
335f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
33600 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
33610 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
33620 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
33630 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
33640 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 e 32-bit signed
33650 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
33660 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
33670 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e d argument..** ^
33680 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33690 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 lt_int64() inter
336a0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
336b0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
336c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
336d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
336e0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 n to be the 64-b
336f0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
33700 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e r.** value given
33710 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 in the 2nd argu
33720 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
33730 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33740 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
33750 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
33760 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
33770 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33780 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
33790 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
337a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
337b0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 ult_text(), sqli
337c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
337d0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6(),.** sqlite3_
337e0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
337f0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
33800 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 esult_text16be()
33810 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 interfaces.** s
33820 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 et the return va
33830 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 lue of the appli
33840 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
33850 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a unction to be.**
33860 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 a text string w
33870 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e hich is represen
33880 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 ted as UTF-8, UT
33890 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
338a0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 order,.** UTF-1
338b0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 6 little endian,
338c0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 or UTF-16 big e
338d0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 ndian, respectiv
338e0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ely..** ^SQLite
338f0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 takes the text r
33900 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 esult from the a
33910 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a pplication from.
33920 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d ** the 2nd param
33930 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 eter of the sqli
33940 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
33950 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
33960 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 ^If the 3rd para
33970 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
33980 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
33990 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
339a0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
339b0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 n SQLite takes r
339c0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 esult text from
339d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
339e0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 r.** through the
339f0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
33a00 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
33a10 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
33a20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
33a30 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
33a40 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e rfaces.** is non
33a50 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
33a60 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e as many bytes (n
33a70 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f ot characters) o
33a80 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f f the text.** po
33a90 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
33aa0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 2nd parameter ar
33ab0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 e taken as the a
33ac0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
33ad0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 ed.** function r
33ae0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 esult. If the 3
33af0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
33b00 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
33b10 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 en it.** must be
33b20 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 the byte offset
33b30 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 into the string
33b40 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 where the NUL t
33b50 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a erminator would.
33b60 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 ** appear if the
33b70 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 string where NU
33b80 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 L terminated. I
33b90 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 f any NUL charac
33ba0 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ters occur.** in
33bb0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 the string at a
33bc0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 byte offset tha
33bd0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 t is less than t
33be0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
33bf0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 3rd.** parameter
33c00 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c , then the resul
33c10 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c ting string will
33c20 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
33c30 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a d NULs and the.*
33c40 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 * result of expr
33c50 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e essions operatin
33c60 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 g on strings wit
33c70 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 h embedded NULs
33c80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
33c90 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
33ca0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
33cb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
33cc0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
33cd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
33ce0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
33cf0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
33d00 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
33d10 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
33d20 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
33d30 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
33d40 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
33d50 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
33d60 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
33d70 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
33d80 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
33d90 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
33da0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
33db0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a nterfaces or to.
33dc0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
33dd0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
33de0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
33df0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 QLITE_STATIC, th
33e00 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 en SQLite.** ass
33e10 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 umes that the te
33e20 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
33e30 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 t is in constant
33e40 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
33e50 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 not.** copy the
33e60 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 content of the p
33e70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c arameter nor cal
33e80 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f l a destructor o
33e90 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a n the content.**
33ea0 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
33eb0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
33ec0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
33ed0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
33ee0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
33ef0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
33f00 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
33f10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
33f20 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
33f30 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
33f40 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 E_TRANSIENT.** t
33f50 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 hen SQLite makes
33f60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 a copy of the r
33f70 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 esult into space
33f80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a obtained from.*
33f90 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
33fa0 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 malloc()] before
33fb0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a it returns..**.
33fc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
33fd0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
33fe0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
33ff0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
34000 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
34010 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
34020 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 to be a copy the
34030 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
34040 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
34050 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 object specified
34060 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
34070 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 meter. ^The.**
34080 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
34090 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
340a0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
340b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
340c0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
340d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
340e0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
340f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
34100 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
34110 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
34120 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
34130 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
34140 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
34150 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 ..** ^A [protect
34160 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
34170 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 ] object may alw
34180 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 ays be used wher
34190 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 e an.** [unprote
341a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
341b0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 ue] object is re
341c0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 quired, so eithe
341d0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 r.** kind of [sq
341e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
341f0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 ect can be used
34200 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 with this interf
34210 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ace..**.** If th
34220 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
34230 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
34240 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e hin the differen
34250 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e t thread.** than
34260 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e the one contain
34270 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 ing the applicat
34280 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
34290 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 tion that receiv
342a0 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ed.** the [sqlit
342b0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e e3_context] poin
342c0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 ter, the results
342d0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
342e0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
342f0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 result_blob(sqli
34300 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
34310 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
34320 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
34330 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
34340 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 sult_double(sqli
34350 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f te3_context*, do
34360 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 uble);.void sqli
34370 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
34380 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
34390 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 *, const char*,
343a0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
343b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
343c0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 6(sqlite3_contex
343d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
343e0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
343f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
34400 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f _toobig(sqlite3_
34410 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 context*);.void
34420 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
34430 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 rror_nomem(sqlit
34440 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
34450 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
34460 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c t_error_code(sql
34470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
34480 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
34490 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 3_result_int(sql
344a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
344b0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 nt);.void sqlite
344c0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 3_result_int64(s
344d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
344e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b sqlite3_int64);
344f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
34500 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 sult_null(sqlite
34510 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
34520 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34530 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f _text(sqlite3_co
34540 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
34550 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a ar*, int, void(*
34560 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
34570 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
34580 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f ext16(sqlite3_co
34590 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
345a0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a id*, int, void(*
345b0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
345c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
345d0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
345e0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
345f0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
34600 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
34610 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34620 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 text16be(sqlite3
34630 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
34640 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 void*, int,void
34650 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
34660 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34670 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 _value(sqlite3_c
34680 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
34690 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 _value*);.void s
346a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
346b0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 roblob(sqlite3_c
346c0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b ontext*, int n);
346d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
346e0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
346f0 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
34700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
34710 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d nctions add, rem
34720 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 ove, or modify a
34730 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 [collation] ass
34740 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
34750 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
34760 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
34770 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
34780 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
34790 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 ^The name of th
347a0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 e collation is a
347b0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
347c0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
347d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 ate_collation()
347e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 and sqlite3_crea
347f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
34800 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 ).** and a UTF-1
34810 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
34820 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f ve byte order fo
34830 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
34840 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a _collation16()..
34850 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 ** ^Collation na
34860 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 mes that compare
34870 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 equal according
34880 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 to [sqlite3_str
34890 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 nicmp()] are.**
348a0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
348b0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
348c0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 **.** ^(The thir
348d0 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 d argument (eTex
348e0 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e tRep) must be on
348f0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
34900 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ts:.** <ul>.** <
34910 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 li> [SQLITE_UTF8
34920 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
34930 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 TE_UTF16LE],.**
34940 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
34950 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 16BE],.** <li> [
34960 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f SQLITE_UTF16], o
34970 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
34980 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
34990 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ..** </ul>)^.**
349a0 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 ^The eTextRep ar
349b0 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 gument determine
349c0 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f s the encoding o
349d0 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 f strings passed
349e0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 .** to the colla
349f0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
34a00 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 llback, xCallbac
34a10 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 k..** ^The [SQLI
34a20 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 TE_UTF16] and [S
34a30 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
34a40 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 NED] values for
34a50 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 eTextRep.** forc
34a60 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 e strings to be
34a70 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 UTF16 with nativ
34a80 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
34a90 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 ^The [SQLITE_UT
34aa0 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c F16_ALIGNED] val
34ab0 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 ue for eTextRep
34ac0 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 forces strings t
34ad0 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e o begin.** on an
34ae0 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 even byte addre
34af0 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ss..**.** ^The f
34b00 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
34b10 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c pArg, is an appl
34b20 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
34b30 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
34b40 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 sed.** through a
34b50 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
34b60 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c ment to the coll
34b70 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
34b80 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
34b90 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
34ba0 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 nt, xCallback, i
34bb0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
34bc0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
34bd0 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 ction..** ^Multi
34be0 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ple collating fu
34bf0 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 nctions can be r
34c00 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
34c10 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
34c20 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 t.** with differ
34c30 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 ent eTextRep par
34c40 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 ameters and SQLi
34c50 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 te will use whic
34c60 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f hever.** functio
34c70 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c n requires the l
34c80 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
34c90 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 ata transformati
34ca0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 on..** ^If the x
34cb0 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e Callback argumen
34cc0 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 t is NULL then t
34cd0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
34ce0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 ction is.** dele
34cf0 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 ted. ^When all
34d00 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
34d10 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 ons having the s
34d20 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c ame name are del
34d30 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f eted,.** that co
34d40 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f llation is no lo
34d50 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a nger usable..**.
34d60 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e ** ^The collatin
34d70 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
34d80 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
34d90 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ith a copy of th
34da0 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 e pArg .** appli
34db0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
34dc0 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f ter and with two
34dd0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
34de0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
34df0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 ed.** by the eTe
34e00 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 xtRep argument.
34e10 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
34e20 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 unction must ret
34e30 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 urn an.** intege
34e40 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 r that is negati
34e50 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 ve, zero, or pos
34e60 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 itive.** if the
34e70 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
34e80 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c less than, equal
34e90 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
34ea0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c than the second,
34eb0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
34ec0 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 . A collating f
34ed0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 unction must alw
34ee0 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
34ef0 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 ame answer.** gi
34f00 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 ven the same inp
34f10 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 uts. If two or
34f20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 more collating f
34f30 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 unctions are reg
34f40 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 istered.** to th
34f50 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e e same collation
34f60 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 name (using dif
34f70 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
34f80 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c values) then all
34f90 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e .** must give an
34fa0 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 equivalent answ
34fb0 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 er when invoked
34fc0 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 with equivalent
34fd0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 strings..** The
34fe0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
34ff0 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 on must obey the
35000 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 following prope
35010 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a rties for all.**
35020 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 strings A, B, a
35030 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e nd C:.**.** <ol>
35040 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
35050 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c then B==A..** <
35060 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 li> If A==B and
35070 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a B==C then A==C..
35080 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
35090 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a B THEN B>A..*
350a0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
350b0 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e and B<C then
350c0 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c A<C..** </ol
350d0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c >.**.** If a col
350e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
350f0 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 fails any of the
35100 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e above constrain
35110 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 ts and that.** c
35120 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
35130 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 n is registered
35140 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 and used, then
35150 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
35160 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 SQLite.** is und
35170 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
35180 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
35190 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
351a0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
351b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
351c0 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 tion().** with t
351d0 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 he addition that
351e0 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 the xDestroy ca
351f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
35200 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a d on pArg when.*
35210 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 * the collating
35220 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 function is dele
35230 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 ted..** ^Collati
35240 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ng functions are
35250 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 deleted when th
35260 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
35270 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 n by later.** ca
35280 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 lls to the colla
35290 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
352a0 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
352b0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
352c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
352d0 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 closed using [sq
352e0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
352f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 **.** ^The xDest
35300 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 roy callback is
35310 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 <u>not</u> calle
35320 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c d if the .** sql
35330 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
35340 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 ation_v2() funct
35350 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c ion fails. Appl
35360 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e ications that in
35370 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
35380 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
35390 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e _v2() with a non
353a0 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 -NULL xDestroy a
353b0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a rgument should .
353c0 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ** check the ret
353d0 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 urn code and dis
353e0 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c pose of the appl
353f0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
35400 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 nter.** themselv
35410 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 es rather than e
35420 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 xpecting SQLite
35430 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 to deal with it
35440 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 for them..** Thi
35450 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 s is different f
35460 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 rom every other
35470 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
35480 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 . The inconsist
35490 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f ency .** is unfo
354a0 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e rtunate but cann
354b0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 ot be changed wi
354c0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 thout breaking b
354d0 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d ackwards .** com
354e0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
354f0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 * See also: [sq
35500 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
35510 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 needed()] and [s
35520 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
35530 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f _needed16()]..*/
35540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
35550 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 ate_collation(.
35560 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
35570 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
35580 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
35590 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
355a0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
355b0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
355c0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
355d0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 t void*).);.int
355e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
355f0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 ollation_v2(. s
35600 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
35610 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
35620 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
35630 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 . void *pArg,.
35640 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
35650 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
35660 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
35670 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a void*),. void(*
35680 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 xDestroy)(void*)
35690 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
356a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
356b0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
356c0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
356d0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 Name,. int eTex
356e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
356f0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
35700 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
35710 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
35720 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
35730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
35740 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 Collation Neede
35750 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a d Callbacks.**.*
35760 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 * ^To avoid havi
35770 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 ng to register a
35780 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ll collation seq
35790 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 uences before a
357a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 database.** can
357b0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c be used, a singl
357c0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
357d0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
357e0 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a tered with the.*
357f0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
35800 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e ection] to be in
35810 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 voked whenever a
35820 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c n undefined coll
35830 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 ation.** sequenc
35840 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a e is required..*
35850 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e *.** ^If the fun
35860 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 ction is registe
35870 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 red using the sq
35880 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
35890 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a needed() API,.**
358a0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 then it is pass
358b0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 ed the names of
358c0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 undefined collat
358d0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 ion sequences as
358e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f strings.** enco
358f0 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 ded in UTF-8. ^I
35900 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 f sqlite3_collat
35910 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 ion_needed16() i
35920 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e s used,.** the n
35930 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 ames are passed
35940 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 as UTF-16 in mac
35950 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 hine native byte
35960 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 order..** ^A ca
35970 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e ll to either fun
35980 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 ction replaces t
35990 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c he existing coll
359a0 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c ation-needed cal
359b0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 lback..**.** ^(W
359c0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
359d0 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 is invoked, the
359e0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
359f0 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 passed is a copy
35a00 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e .** of the secon
35a10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
35a20 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
35a30 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 needed() or.** s
35a40 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
35a50 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 _needed16(). Th
35a60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
35a70 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 t is the databas
35a80 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
35a90 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
35aa0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b ment is one of [
35ab0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 SQLITE_UTF8], [S
35ac0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
35ad0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ** or [SQLITE_UT
35ae0 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 F16LE], indicati
35af0 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 ng the most desi
35b00 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 rable form of th
35b10 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 e collation.** s
35b20 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e equence function
35b30 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 required. The
35b40 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
35b50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
35b60 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 the.** required
35b70 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
35b80 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ce.)^.**.** The
35b90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
35ba0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 n should registe
35bb0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f r the desired co
35bc0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a llation using.**
35bd0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
35be0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b _collation()], [
35bf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
35c00 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f ollation16()], o
35c10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 r.** [sqlite3_cr
35c20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
35c30 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 2()]..*/.int sql
35c40 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
35c50 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 eeded(. sqlite3
35c60 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 *, . void*, .
35c70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
35c80 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
35c90 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 Rep,const char*)
35ca0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
35cb0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
35cc0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 16(. sqlite3*,
35cd0 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 . void*,. void
35ce0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
35cf0 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
35d00 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
35d10 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 .#ifdef SQLITE_H
35d20 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 AS_CODEC./*.** S
35d30 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 pecify the key f
35d40 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 or an encrypted
35d50 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 database. This
35d60 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 routine should b
35d70 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 e.** called righ
35d80 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f t after sqlite3_
35d90 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 open()..**.** Th
35da0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
35db0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
35dc0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
35dd0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
35de0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
35df0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
35e00 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 _key(. sqlite3
35e10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
35e20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
35e30 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
35e40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
35e50 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 *pKey, int nKey
35e60 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 /* The key
35e70 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 */.);../*.** Cha
35e80 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 nge the key on a
35e90 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e n open database.
35ea0 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 If the current
35eb0 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 database is not
35ec0 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 .** encrypted, t
35ed0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c his routine will
35ee0 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 encrypt it. If
35ef0 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 pNew==0 or nNew
35f00 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 ==0, the.** data
35f10 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 base is decrypte
35f20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 d..**.** The cod
35f30 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 e to implement t
35f40 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 his API is not a
35f50 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 vailable in the
35f60 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a public release.*
35f70 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a * of SQLite..*/.
35f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 int sqlite3_reke
35f90 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 y(. sqlite3 *db
35fa0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
35fb0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
35fc0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
35fd0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
35fe0 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
35ff0 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 /* The new key
36000 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 */.);../*.** Sp
36010 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 ecify the activa
36020 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 tion key for a S
36030 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e EE database. Un
36040 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 less .** activat
36050 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 ed, none of the
36060 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c SEE routines wil
36070 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 l work..*/.void
36080 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
36090 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 _see(. const ch
360a0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 ar *zPassPhrase
360b0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 /* Activa
360c0 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 tion phrase */.)
360d0 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 ;.#endif..#ifdef
360e0 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 SQLITE_ENABLE_C
360f0 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 EROD./*.** Speci
36100 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f fy the activatio
36110 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f n key for a CERO
36120 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c D database. Unl
36130 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 ess .** activate
36140 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 d, none of the C
36150 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 EROD routines wi
36160 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 ll work..*/.void
36170 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 sqlite3_activat
36180 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 e_cerod(. const
36190 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 char *zPassPhra
361a0 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 se /* Act
361b0 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a ivation phrase *
361c0 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a /.);.#endif../*.
361d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 ** CAPI3REF: Sus
361e0 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 pend Execution F
361f0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a or A Short Time.
36200 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
36210 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 3_sleep() functi
36220 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 on causes the cu
36230 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 rrent thread to
36240 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f suspend executio
36250 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 n.** for at leas
36260 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 t a number of mi
36270 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 lliseconds speci
36280 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 fied in its para
36290 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 meter..**.** If
362a0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
362b0 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 stem does not su
362c0 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 pport sleep requ
362d0 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c ests with.** mil
362e0 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 lisecond time re
362f0 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 solution, then t
36300 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 he time will be
36310 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a rounded up to.**
36320 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 the nearest sec
36330 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 ond. The number
36340 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
36350 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c of sleep actuall
36360 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 y.** requested f
36370 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e rom the operatin
36380 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 g system is retu
36390 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c rned..**.** ^SQL
363a0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 ite implements t
363b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 his interface by
363c0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c calling the xSl
363d0 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 eep().** method
363e0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b of the default [
363f0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
36400 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c ect. If the xSl
36410 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 eep() method.**
36420 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 of the default V
36430 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d FS is not implem
36440 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c ented correctly,
36450 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e or not implemen
36460 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 ted at.** all, t
36470 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
36480 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 of sqlite3_slee
36490 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 p() may deviate
364a0 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 from the descrip
364b0 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 tion.** in the p
364c0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
364d0 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 hs..*/.int sqlit
364e0 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a e3_sleep(int);..
364f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36500 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 Name Of The Fold
36510 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f er Holding Tempo
36520 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a rary Files.**.**
36530 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ^(If this globa
36540 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
36550 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
36560 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
36570 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
36580 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e a folder (a.k.a.
36590 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 directory), the
365a0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 n all temporary
365b0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 files.** created
365c0 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 by SQLite when
365d0 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e using a built-in
365e0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
365f0 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 VFS].** will be
36600 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 placed in that d
36610 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 irectory.)^ ^If
36620 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a this variable.*
36630 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e * is a NULL poin
36640 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 ter, then SQLite
36650 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 performs a sear
36660 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 ch for an approp
36670 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 riate.** tempora
36680 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 ry file director
36690 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e y..**.** It is n
366a0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
366b0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
366c0 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 ariable in more
366d0 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 than one.** thre
366e0 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 ad at a time. I
366f0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f t is not safe to
36700 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 read or modify
36710 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
36720 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 if a [database
36730 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 connection] is b
36740 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 eing used at the
36750 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 same time in a
36760 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 separate.** thre
36770 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 ad..** It is int
36780 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 ended that this
36790 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 variable be set
367a0 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 once.** as part
367b0 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 of process initi
367c0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 alization and be
367d0 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 fore any SQLite
367e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 interface.** rou
367f0 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 tines have been
36800 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 called and that
36810 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 this variable re
36820 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a main unchanged.*
36830 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a * thereafter..**
36840 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 .** ^The [temp_s
36850 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
36860 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 ragma] may modif
36870 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
36880 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 and cause.** it
36890 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f to point to memo
368a0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
368b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
368c0 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 ]. ^Furthermore
368d0 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 ,.** the [temp_s
368e0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
368f0 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 ragma] always as
36900 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 sumes that any s
36910 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 tring.** that th
36920 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e is variable poin
36930 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e ts to is held in
36940 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
36950 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 from .** [sqlit
36960 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 e3_malloc] and t
36970 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 he pragma may at
36980 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 tempt to free th
36990 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 at memory.** usi
369a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
369b0 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 ]..** Hence, if
369c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 this variable is
369d0 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 modified direct
369e0 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 ly, either it sh
369f0 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 ould be.** made
36a00 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 NULL or made to
36a10 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 point to memory
36a20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
36a30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a qlite3_malloc].*
36a40 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 * or else the us
36a50 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 e of the [temp_s
36a60 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 tore_directory p
36a70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 ragma] should be
36a80 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 avoided..**.**
36a90 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f <b>Note to Windo
36aa0 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 ws Runtime users
36ab0 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f :</b> The tempo
36ac0 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d rary directory m
36ad0 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 ust be set.** pr
36ae0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b ior to calling [
36af0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 sqlite3_open] or
36b00 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
36b10 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 2]. Otherwise,
36b20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 various.** featu
36b30 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 res that require
36b40 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 the use of temp
36b50 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 orary files may
36b60 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61 fail. Here is a
36b70 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 n.** example of
36b80 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75 how to do this u
36b90 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68 sing C++ with th
36ba0 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d e Windows Runtim
36bb0 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 e:.**.** <blockq
36bc0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 uote><pre>.** LP
36bd0 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69 CWSTR zPath = Wi
36be0 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a ndows::Storage::
36bf0 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a ApplicationData:
36c00 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e :Current->.** &n
36c10 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72 61 bsp; Tempora
36c20 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e ryFolder->Path->
36c30 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20 Data();.** char
36c40 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41 58 zPathBuf[MAX
36c50 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a _PATH + 1];.
36c60 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68 42 ** memset(zPathB
36c70 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50 uf, 0, sizeof(zP
36c80 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64 athBuf));.** Wid
36c90 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74 65 eCharToMultiByte
36ca0 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61 (CP_UTF8, 0, zPa
36cb0 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75 66 th, -1, zPathBuf
36cc0 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 , sizeof(zPathBu
36cd0 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 f),.**
36ce0 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a NULL, NULL);.*
36cf0 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 * sqlite3_temp_d
36d00 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69 74 irectory = sqlit
36d10 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22 2c e3_mprintf("%s",
36d20 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c zPathBuf);.** <
36d30 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
36d40 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 e>.*/.SQLITE_EXT
36d50 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 ERN char *sqlite
36d60 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
36d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
36d80 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 F: Name Of The F
36d90 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 older Holding Da
36da0 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a tabase Files.**.
36db0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f ** ^(If this glo
36dc0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 bal variable is
36dd0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
36de0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
36df0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f is.** the name o
36e00 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e f a folder (a.k.
36e10 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 a. directory), t
36e20 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65 hen all database
36e30 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 files.** specif
36e40 69 65 64 20 77 69 74 68 20 61 20 72 65 6c 61 74 ied with a relat
36e50 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 ive pathname and
36e60 20 63 72 65 61 74 65 64 20 6f 72 20 61 63 63 65 created or acce
36e70 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 ssed by.** SQLit
36e80 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 e when using a b
36e90 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 uilt-in windows
36ea0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 [sqlite3_vfs | V
36eb0 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75 FS] will be assu
36ec0 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c med.** to be rel
36ed0 61 74 69 76 65 20 74 6f 20 74 68 61 74 20 64 69 ative to that di
36ee0 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 rectory.)^ ^If t
36ef0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
36f00 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
36f10 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 r, then SQLite a
36f20 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 ssumes that all
36f30 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 73 database files s
36f40 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 pecified.** with
36f50 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
36f60 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76 name are relativ
36f70 65 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 e to the current
36f80 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f directory.** fo
36f90 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20 r the process.
36fa0 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73 Only the windows
36fb0 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f VFS makes use o
36fc0 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a f this global.**
36fd0 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73 variable; it is
36fe0 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20 ignored by the
36ff0 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 unix VFS..**.**
37000 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c Changing the val
37010 75 65 20 6f 66 20 74 68 69 73 20 76 61 72 69 61 ue of this varia
37020 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61 74 61 ble while a data
37030 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
37040 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 is.** open can r
37050 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 esult in a corru
37060 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a pt database..**.
37070 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 ** It is not saf
37080 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 e to read or mod
37090 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
370a0 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f e in more than o
370b0 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 ne.** thread at
370c0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e a time. It is n
370d0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
370e0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
370f0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 ariable.** if a
37100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
37110 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 tion] is being u
37120 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 sed at the same
37130 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 time in a separa
37140 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a te.** thread..**
37150 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 It is intended
37160 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
37170 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a le be set once.*
37180 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f * as part of pro
37190 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 cess initializat
371a0 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 ion and before a
371b0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
371c0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ace.** routines
371d0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
371e0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 and that this v
371f0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 ariable remain u
37200 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 nchanged.** ther
37210 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eafter..**.** ^T
37220 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 he [data_store_d
37230 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
37240 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 may modify this
37250 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 variable and ca
37260 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 use.** it to poi
37270 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 nt to memory obt
37280 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
37290 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 te3_malloc]. ^F
372a0 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 urthermore,.** t
372b0 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 he [data_store_d
372c0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
372d0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 always assumes
372e0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a that any string.
372f0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 ** that this var
37300 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 iable points to
37310 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 is held in memor
37320 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
37330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
37340 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 loc] and the pra
37350 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 gma may attempt
37360 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d to free that mem
37370 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 ory.** using [sq
37380 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 lite3_free]..**
37390 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 Hence, if this v
373a0 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 ariable is modif
373b0 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 ied directly, ei
373c0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 ther it should b
373d0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f e.** made NULL o
373e0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 r made to point
373f0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
37400 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
37410 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 _malloc].** or e
37420 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 lse the use of t
37430 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 he [data_store_d
37440 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
37450 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 should be avoid
37460 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 ed..*/.SQLITE_EX
37470 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 TERN char *sqlit
37480 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74 6f 72 e3_data_director
37490 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 y;../*.** CAPI3R
374a0 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 EF: Test For Aut
374b0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a o-Commit Mode.**
374c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f KEYWORDS: {auto
374d0 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a commit mode}.**.
374e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
374f0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 get_autocommit()
37500 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
37510 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a ns non-zero or.*
37520 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 * zero if the gi
37530 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e ven database con
37540 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 nection is or is
37550 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d not in autocomm
37560 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 it mode,.** resp
37570 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f ectively. ^Auto
37580 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f commit mode is o
37590 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a n by default..**
375a0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
375b0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 e is disabled by
375c0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 a [BEGIN] state
375d0 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f ment..** ^Autoco
375e0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d mmit mode is re-
375f0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f enabled by a [CO
37600 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 MMIT] or [ROLLBA
37610 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 CK]..**.** If ce
37620 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 rtain kinds of e
37630 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 rrors occur on a
37640 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
37650 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d n a multi-statem
37660 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 ent.** transacti
37670 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 on (errors inclu
37680 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c ding [SQLITE_FUL
37690 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 L], [SQLITE_IOER
376a0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e R],.** [SQLITE_N
376b0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 OMEM], [SQLITE_B
376c0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 USY], and [SQLIT
376d0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 E_INTERRUPT]) th
376e0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 en the.** transa
376f0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 ction might be r
37700 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
37710 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f atically. The o
37720 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 nly way to.** fi
37730 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 nd out whether S
37740 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 QLite automatica
37750 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 lly rolled back
37760 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
37770 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f after.** an erro
37780 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 r is to use this
37790 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
377a0 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 If another thre
377b0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 ad changes the a
377c0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 utocommit status
377d0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
377e0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 .** connection w
377f0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e hile this routin
37800 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 e is running, th
37810 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
37820 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 lue.** is undefi
37830 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ned..*/.int sqli
37840 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d te3_get_autocomm
37850 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f it(sqlite3*);../
37860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
37870 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 ind The Database
37880 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 Handle Of A Pre
37890 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a pared Statement.
378a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
378b0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 e3_db_handle int
378c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
378d0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
378e0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a nection] handle.
378f0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 ** to which a [p
37900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
37910 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 t] belongs. ^Th
37920 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
37930 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 ection].** retur
37940 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 ned by sqlite3_d
37950 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 b_handle is the
37960 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 same [database c
37970 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 onnection].** th
37980 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 at was the first
37990 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
379a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
379b0 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 pare_v2()] call
379c0 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 (or its variants
379d0 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 ) that was used
379e0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 to.** create the
379f0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
37a00 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a e first place..*
37a10 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 /.sqlite3 *sqlit
37a20 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c e3_db_handle(sql
37a30 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
37a40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
37a50 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d turn The Filenam
37a60 65 20 46 6f 72 20 41 20 44 61 74 61 62 61 73 65 e For A Database
37a70 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a Connection.**.*
37a80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
37a90 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 b_filename(D,N)
37aa0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
37ab0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
37ac0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 filename.** ass
37ad0 6f 63 69 61 74 65 64 20 77 69 74 68 20 64 61 74 ociated with dat
37ae0 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 abase N of conne
37af0 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d ction D. ^The m
37b00 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
37b10 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61 6d e.** has the nam
37b20 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 e "main". If th
37b30 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63 68 ere is no attach
37b40 65 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f 6e ed database N on
37b50 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
37b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f connection D, o
37b70 72 20 69 66 20 64 61 74 61 62 61 73 65 20 4e 20 r if database N
37b80 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20 6f is a temporary o
37b90 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 r in-memory data
37ba0 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 base, then.** a
37bb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
37bc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
37bd0 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 ^The filename re
37be0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 turned by this f
37bf0 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6f unction is the o
37c00 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 utput of the.**
37c10 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 xFullPathname me
37c20 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46 53 thod of the [VFS
37c30 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f ]. ^In other wo
37c40 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d rds, the filenam
37c50 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 e.** will be an
37c60 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d absolute pathnam
37c70 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20 66 e, even if the f
37c80 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 ilename used.**
37c90 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
37ca0 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 base originally
37cb0 77 61 73 20 61 20 55 52 49 20 6f 72 20 72 65 6c was a URI or rel
37cc0 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a ative pathname..
37cd0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
37ce0 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 qlite3_db_filena
37cf0 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 me(sqlite3 *db,
37d00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e const char *zDbN
37d10 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ame);../*.** CAP
37d20 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
37d30 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 69 if a database i
37d40 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a 2a s read-only.**.*
37d50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
37d60 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29 20 b_readonly(D,N)
37d70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
37d80 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61 62 s 1 if the datab
37d90 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e 6e ase N.** of conn
37da0 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61 64 ection D is read
37db0 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20 69 -only, 0 if it i
37dc0 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f 72 s read/write, or
37dd0 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74 0a -1 if N is not.
37de0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 ** the name of a
37df0 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f 6e database on con
37e00 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 69 6e nection D..*/.in
37e10 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 t sqlite3_db_rea
37e20 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a 64 donly(sqlite3 *d
37e30 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a b, const char *z
37e40 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 DbName);../*.**
37e50 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 CAPI3REF: Find t
37e60 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 he next prepared
37e70 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a statement.**.**
37e80 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 ^This interface
37e90 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
37ea0 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b er to the next [
37eb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37ec0 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 nt] after.** pSt
37ed0 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 mt associated wi
37ee0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
37ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 connection] pDb
37f00 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 . ^If pStmt is
37f10 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 NULL.** then thi
37f20 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 s interface retu
37f30 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
37f40 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61 the first prepa
37f50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
37f60 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
37f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
37f80 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e nnection pDb. ^
37f90 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 If no prepared s
37fa0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 tatement.** sati
37fb0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 sfies the condit
37fc0 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 ions of this rou
37fd0 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 tine, it returns
37fe0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
37ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
38000 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 ction] pointer D
38010 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a in a call to.**
38020 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
38030 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 tmt(D,S)] must r
38040 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 efer to an open
38050 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
38060 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 ection and in pa
38070 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f rticular must no
38080 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t be a NULL poin
38090 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f ter..*/.sqlite3_
380a0 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 stmt *sqlite3_ne
380b0 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 xt_stmt(sqlite3
380c0 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 *pDb, sqlite3_st
380d0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
380e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
380f0 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b mit And Rollback
38100 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 Notification Ca
38110 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 llbacks.**.** ^T
38120 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 he sqlite3_commi
38130 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 t_hook() interfa
38140 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
38150 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
38160 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ion to be invoke
38170 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 d whenever a tra
38180 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d nsaction is [COM
38190 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d MIT | committed]
381a0 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 ..** ^Any callba
381b0 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 ck set by a prev
381c0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c ious call to sql
381d0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
381e0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 ().** for the sa
381f0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
38200 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 ection is overri
38210 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 dden..** ^The sq
38220 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
38230 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
38240 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
38250 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
38260 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
38270 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
38280 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 ction is [ROLLBA
38290 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b CK | rolled back
382a0 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 ]..** ^Any callb
382b0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
382c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 vious call to sq
382d0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
382e0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
382f0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
38300 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
38310 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 rridden..** ^The
38320 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 pArg argument i
38330 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
38340 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
38350 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c ..** ^If the cal
38360 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 lback on a commi
38370 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 t hook function
38380 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
38390 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ,.** then the co
383a0 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 mmit is converte
383b0 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 d into a rollbac
383c0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 k..**.** ^The sq
383d0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
383e0 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c k(D,C,P) and sql
383f0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
38400 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 ok(D,C,P) functi
38410 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 ons.** return th
38420 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f e P argument fro
38430 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 m the previous c
38440 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 all of the same
38450 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 function.** on t
38460 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
38470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c e connection] D,
38480 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 or NULL for.**
38490 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 the first call f
384a0 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e or each function
384b0 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 on D..**.** The
384c0 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c commit and roll
384d0 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 back hook callba
384e0 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65 65 6e cks are not reen
384f0 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 trant..** The ca
38500 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 llback implement
38510 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 ation must not d
38520 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
38530 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
38540 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
38550 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
38560 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ked the callback
38570 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a . Any actions.*
38580 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 * to modify the
38590 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
385a0 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 ion must be defe
385b0 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 rred until after
385c0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 the.** completi
385d0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
385e0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
385f0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
38600 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 he commit.** or
38610 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e rollback hook in
38620 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 the first place
38630 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 ..** Note that r
38640 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 unning any other
38650 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c SQL statements,
38660 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 including SELEC
38670 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a T statements,.**
38680 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 or merely calli
38690 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
386a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
386b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
386c0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
386d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
386e0 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
386f0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
38700 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
38710 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 raph..**.** ^Reg
38720 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 istering a NULL
38730 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 function disable
38740 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a s the callback..
38750 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 **.** ^When the
38760 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c commit hook call
38770 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 back routine ret
38780 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b urns zero, the [
38790 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 COMMIT].** opera
387a0 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 tion is allowed
387b0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d to continue norm
387c0 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 ally. ^If the c
387d0 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 ommit hook.** re
387e0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
387f0 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 then the [COMMIT
38800 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 ] is converted i
38810 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d nto a [ROLLBACK]
38820 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 ..** ^The rollba
38830 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b ck hook is invok
38840 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b ed on a rollback
38850 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 that results fr
38860 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 om a commit.** h
38870 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f ook returning no
38880 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20