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 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 54 68 65 P_LIMIT]].** The
ab00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [SQLITE_FCNTL_M
ab10: 4d 41 50 5f 4c 49 4d 49 54 5d 20 66 69 6c 65 20 MAP_LIMIT] file
ab20: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
ab30: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 to query or set
ab40: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e the.** maximum n
ab50: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 umber of bytes t
ab60: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 hat will be used
ab70: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 for memory-mapp
ab80: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 ed I/O..** The a
ab90: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
aba0: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 nter to a value
abb0: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f of type sqlite3_
abc0: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 int64 that.** is
abd0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 an advisory max
abe0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 imum number of b
abf0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
ac00: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 to memory map.
ac10: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 The.** pointer
ac20: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
ac30: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 ith the old valu
ac40: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 e. The limit is
ac50: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a not changed if.
ac60: 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 6c ** the originall
ac70: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 y pointed to is
ac80: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f negative, and so
ac90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d the current lim
aca0: 69 74 20 63 61 6e 20 62 65 0a 2a 2a 20 71 75 65 it can be.** que
acb0: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ried by passing
acc0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 in a pointer to
acd0: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 a negative numbe
ace0: 72 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f r. This file-co
acf0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 75 73 65 64 ntrol.** is used
ad00: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 internally to i
ad10: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 mplement [PRAGMA
ad20: 20 6d 6d 61 70 5f 6c 69 6d 69 74 5d 2e 0a 2a 2a mmap_limit]..**
ad30: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 .** </ul>.*/.#de
ad40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ad50: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 L_LOCKSTATE
ad60: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
ad70: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c ine SQLITE_GET_L
ad80: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
ad90: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
ada0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f ne SQLITE_SET_LO
adb0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
adc0: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
add0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 e SQLITE_LAST_ER
ade0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
adf0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
ae00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 SQLITE_FCNTL_SI
ae10: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 ZE_HINT
ae20: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
ae30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
ae40: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 NK_SIZE
ae50: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
ae60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
ae70: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 _POINTER
ae80: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
ae90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f LITE_FCNTL_SYNC_
aea0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 OMITTED
aeb0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
aec0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
aed0: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 AV_RETRY
aee0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
aef0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 TE_FCNTL_PERSIST
af00: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 _WAL
af10: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
af20: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
af30: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 E 1
af40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
af50: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 _FCNTL_VFSNAME
af60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 12
af70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
af80: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f FCNTL_POWERSAFE_
af90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a OVERWRITE 13.
afa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
afb0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 CNTL_PRAGMA
afc0: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 14.#
afd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
afe0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 NTL_BUSYHANDLER
aff0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 15.#d
b000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
b010: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 TL_TEMPFILENAME
b020: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 16.#de
b030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
b040: 4c 5f 4d 4d 41 50 5f 4c 49 4d 49 54 20 20 20 20 L_MMAP_LIMIT
b050: 20 20 20 20 20 20 20 20 20 31 38 0a 0a 2f 2a 0a 18../*.
b060: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 ** CAPI3REF: Mut
b070: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 ex Handle.**.**
b080: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 The mutex module
b090: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 within SQLite d
b0a0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f efines [sqlite3_
b0b0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a mutex] to be an.
b0c0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 ** abstract type
b0d0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a for a mutex obj
b0e0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 ect. The SQLite
b0f0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b core never look
b100: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 s.** at the inte
b110: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 rnal representat
b120: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 ion of an [sqlit
b130: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f e3_mutex]. It o
b140: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 nly.** deals wit
b150: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 h pointers to th
b160: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
b170: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
b180: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 Mutexes are crea
b190: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
b1a0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 e3_mutex_alloc()
b1b0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 ]..*/.typedef st
b1c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 ruct sqlite3_mut
b1d0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 ex sqlite3_mutex
b1e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
b1f0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
b200: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 Object.**.** An
b210: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
b220: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
b230: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 ct defines the i
b240: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e nterface between
b250: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 .** the SQLite c
b260: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 ore and the unde
b270: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 rlying operating
b280: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 system. The "v
b290: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 fs".** in the na
b2a0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 me of the object
b2b0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 stands for "vir
b2c0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
b2d0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b ". See.** the [
b2e0: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 VFS | VFS docume
b2f0: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 ntation] for fur
b300: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e ther information
b310: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 ..**.** The valu
b320: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f e of the iVersio
b330: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 n field is initi
b340: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 ally 1 but may b
b350: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 e larger in.** f
b360: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
b370: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 f SQLite. Addit
b380: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 ional fields may
b390: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 be appended to
b3a0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 this.** object w
b3b0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e hen the iVersion
b3c0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 value is increa
b3d0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 sed. Note that
b3e0: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a the structure.**
b3f0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
b400: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 vfs object chang
b410: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 es in the transa
b420: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ction between.**
b430: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
b440: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 3.5.9 and 3.6.0
b450: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 and yet the iVer
b460: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e sion field was n
b470: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a ot.** modified..
b480: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 **.** The szOsFi
b490: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 le field is the
b4a0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 size of the subc
b4b0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f lassed [sqlite3_
b4c0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 file].** structu
b4d0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 re used by this
b4e0: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 VFS. mxPathname
b4f0: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 is the maximum
b500: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 length of.** a p
b510: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 athname in this
b520: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 VFS..**.** Regis
b530: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 tered sqlite3_vf
b540: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 s objects are ke
b550: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c pt on a linked l
b560: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a ist formed by.**
b570: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 the pNext point
b580: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 er. The [sqlite
b590: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 3_vfs_register()
b5a0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
b5b0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 3_vfs_unregister
b5c0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d ()] interfaces m
b5d0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a anage this list.
b5e0: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 ** in a thread-s
b5f0: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 afe way. The [s
b600: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 qlite3_vfs_find(
b610: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
b620: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 searches the lis
b630: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 t. Neither the
b640: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 application code
b650: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 nor the VFS.**
b660: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 implementation s
b670: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e hould use the pN
b680: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ext pointer..**.
b690: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 ** The pNext fie
b6a0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 ld is the only f
b6b0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 ield in the sqli
b6c0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 te3_vfs.** struc
b6d0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 ture that SQLite
b6e0: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 will ever modif
b6f0: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 y. SQLite will
b700: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f only access.** o
b710: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 r modify this fi
b720: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e eld while holdin
b730: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 g a particular s
b740: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 tatic mutex..**
b750: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
b760: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 should never mod
b770: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 ify anything wit
b780: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hin the sqlite3_
b790: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e vfs.** object on
b7a0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 ce the object ha
b7b0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 s been registere
b7c0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 d..**.** The zNa
b7d0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 me field holds t
b7e0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 he name of the V
b7f0: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 FS module. The
b800: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 name must.** be
b810: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c unique across al
b820: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a l VFS modules..*
b830: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 *.** [[sqlite3_v
b840: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 fs.xOpen]].** ^S
b850: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 QLite guarantees
b860: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e that the zFilen
b870: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f ame parameter to
b880: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 xOpen.** is eit
b890: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
b8a0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 er or string obt
b8b0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 ained.** from xF
b8c0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 ullPathname() wi
b8d0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 th an optional s
b8e0: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 uffix added..**
b8f0: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 ^If a suffix is
b900: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 added to the zFi
b910: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
b920: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e , it will.** con
b930: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 sist of a single
b940: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 "-" character f
b950: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f ollowed by no mo
b960: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c re than.** 11 al
b970: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f phanumeric and/o
b980: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 r "-" characters
b990: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 ..** ^SQLite fur
b9a0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 ther guarantees
b9b0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 that.** the stri
b9c0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 ng will be valid
b9d0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 and unchanged u
b9e0: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 ntil xClose() is
b9f0: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 .** called. Beca
ba00: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 use of the previ
ba10: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a ous sentence,.**
ba20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
ba30: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 le] can safely s
ba40: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 tore a pointer t
ba50: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d o the.** filenam
ba60: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f e if it needs to
ba70: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 remember the fi
ba80: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 lename for some
ba90: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 reason..** If th
baa0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
bab0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 meter to xOpen i
bac0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
bad0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d then xOpen.** m
bae0: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f ust invent its o
baf0: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d wn temporary nam
bb00: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 e for the file.
bb10: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a ^Whenever the .
bb20: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 ** xFilename par
bb30: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 ameter is NULL i
bb40: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 t will also be t
bb50: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 he case that the
bb60: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 .** flags parame
bb70: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 ter will include
bb80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
bb90: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a LETEONCLOSE]..**
bba0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 .** The flags ar
bbb0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 gument to xOpen(
bbc0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 ) includes all b
bbd0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 its set in.** th
bbe0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
bbf0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
bc00: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 n_v2()]. Or if
bc10: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
bc20: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
bc30: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 open16()] is use
bc40: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e d, then flags in
bc50: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a cludes at least.
bc60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
bc70: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 READWRITE] | [SQ
bc80: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
bc90: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 ]. .** If xOpen(
bca0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 ) opens a file r
bcb0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 ead-only then it
bcc0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 sets *pOutFlags
bcd0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b to.** include [
bce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
bcf0: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 ONLY]. Other bi
bd00: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 ts in *pOutFlags
bd10: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a may be set..**.
bd20: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c ** ^(SQLite will
bd30: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
bd40: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
bd50: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
bd60: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 n().** call, dep
bd70: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 ending on the ob
bd80: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 ject being opene
bd90: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a d:.**.** <ul>.**
bda0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
bdb0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 PEN_MAIN_DB].**
bdc0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
bdd0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d EN_MAIN_JOURNAL]
bde0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
bdf0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a E_OPEN_TEMP_DB].
be00: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
be10: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
be20: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
be30: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 LITE_OPEN_TRANSI
be40: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 ENT_DB].** <li>
be50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 [SQLITE_OPEN_SU
be60: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 BJOURNAL].** <li
be70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
be80: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a MASTER_JOURNAL].
be90: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
bea0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f _OPEN_WAL].** </
beb0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ul>)^.**.** The
bec0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 file I/O impleme
bed0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 ntation can use
bee0: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 the object type
bef0: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e flags to.** chan
bf00: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 ge the way it de
bf10: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 als with files.
bf20: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e For example, an
bf30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
bf40: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 that does not ca
bf50: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 re about crash r
bf60: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 ecovery or rollb
bf70: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a ack might make.*
bf80: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 * the open of a
bf90: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e journal file a n
bfa0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f o-op. Writes to
bfb0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f this journal wo
bfc0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e uld.** also be n
bfd0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 o-ops, and any a
bfe0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 ttempt to read t
bff0: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 he journal would
c000: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 return.** SQLIT
c010: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 E_IOERR. Or the
c020: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
c030: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 might recognize
c040: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a that a database.
c050: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 ** file will be
c060: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e doing page-align
c070: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 ed sector reads
c080: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 and writes in a
c090: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 random.** order
c0a0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 and set up its I
c0b0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 /O subsystem acc
c0c0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ordingly..**.**
c0d0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 SQLite might als
c0e0: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 o add one of the
c0f0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 following flags
c100: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 to the xOpen me
c110: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
c120: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
c130: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
c140: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 OSE].** <li> [SQ
c150: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
c160: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a IVE].** </ul>.**
c170: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c180: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
c190: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 SE] flag means t
c1a0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
c1b0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 e.** deleted whe
c1c0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 n it is closed.
c1d0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
c1e0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
c1f0: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 ].** will be set
c200: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 for TEMP databa
c210: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f ses and their jo
c220: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e urnals, transien
c230: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 t.** databases,
c240: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e and subjournals.
c250: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
c260: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
c270: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 VE] flag is alwa
c280: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 ys used in conju
c290: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 nction.** with t
c2a0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
c2b0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 CREATE] flag, wh
c2c0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 ich are both dir
c2d0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f ectly.** analogo
c2e0: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c us to the O_EXCL
c2f0: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 and O_CREAT fla
c300: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 gs of the POSIX
c310: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 open().** API.
c320: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f The SQLITE_OPEN_
c330: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 EXCLUSIVE flag,
c340: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 when paired with
c350: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f the .** SQLITE_
c360: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 OPEN_CREATE, is
c370: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 used to indicate
c380: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c that file shoul
c390: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 d always.** be c
c3a0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 reated, and that
c3b0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 it is an error
c3c0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 if it already ex
c3d0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c ists..** It is <
c3e0: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 i>not</i> used t
c3f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 o indicate the f
c400: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 ile should be op
c410: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 ened .** for exc
c420: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a lusive access..*
c430: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 *.** ^At least s
c440: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 zOsFile bytes of
c450: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f memory are allo
c460: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a cated by SQLite.
c470: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 ** to hold the
c480: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 [sqlite3_file] s
c490: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 tructure passed
c4a0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 as the third.**
c4b0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
c4c0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 n. The xOpen me
c4d0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 thod does not ha
c4e0: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 ve to.** allocat
c4f0: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b e the structure;
c500: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 it should just
c510: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 fill it in. Not
c520: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f e that.** the xO
c530: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 pen method must
c540: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
c550: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f file.pMethods to
c560: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c either.** a val
c570: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d id [sqlite3_io_m
c580: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f ethods] object o
c590: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 r to NULL. xOpe
c5a0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 n must do.** thi
c5b0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 s even if the op
c5c0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 en fails. SQLit
c5d0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 e expects that t
c5e0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
c5f0: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d pMethods.** elem
c600: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 ent will be vali
c610: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 d after xOpen re
c620: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 turns regardless
c630: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a of the success.
c640: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 ** or failure of
c650: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e the xOpen call.
c660: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 .**.** [[sqlite3
c670: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a _vfs.xAccess]].*
c680: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 * ^The flags arg
c690: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 ument to xAccess
c6a0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 () may be [SQLIT
c6b0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d E_ACCESS_EXISTS]
c6c0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 .** to test for
c6d0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 the existence of
c6e0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c a file, or [SQL
c6f0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
c700: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 RITE] to.** test
c710: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
c720: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 is readable and
c730: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 writable, or [SQ
c740: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
c750: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 ].** to test whe
c760: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 ther a file is a
c770: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 t least readable
c780: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e . The file can
c790: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f be a.** directo
c7a0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ry..**.** ^SQLit
c7b0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c e will always al
c7c0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 locate at least
c7d0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 mxPathname+1 byt
c7e0: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 es for the.** ou
c7f0: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c tput buffer xFul
c800: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 lPathname. The
c810: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 exact size of th
c820: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a e output buffer.
c830: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 ** is also passe
c840: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 d as a parameter
c850: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 to both method
c860: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 s. If the output
c870: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f buffer.** is no
c880: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 t large enough,
c890: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
c8a0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 ] should be retu
c8b0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 rned. Since this
c8c0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 is.** handled a
c8d0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 s a fatal error
c8e0: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 by SQLite, vfs i
c8f0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 mplementations s
c900: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a hould endeavor.*
c910: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 * to prevent thi
c920: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 s by setting mxP
c930: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 athname to a suf
c940: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 ficiently large
c950: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
c960: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 xRandomness(),
c970: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 xSleep(), xCurre
c980: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 ntTime(), and xC
c990: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 urrentTimeInt64(
c9a0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 ).** interfaces
c9b0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 are not strictly
c9c0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 a part of the f
c9d0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 ilesystem, but t
c9e0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 hey are.** inclu
c9f0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 ded in the VFS s
ca00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d tructure for com
ca10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 pleteness..** Th
ca20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 e xRandomness()
ca30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 function attempt
ca40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 s to return nByt
ca50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 es bytes.** of g
ca60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 ood-quality rand
ca70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 omness into zOut
ca80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 . The return va
ca90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 lue is.** the ac
caa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 tual number of b
cab0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
cac0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 ss obtained..**
cad0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 The xSleep() met
cae0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 hod causes the c
caf0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f alling thread to
cb00: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a sleep for at.**
cb10: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 least the numbe
cb20: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 r of microsecond
cb30: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 s given. ^The x
cb40: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a CurrentTime().**
cb50: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
cb60: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d a Julian Day Num
cb70: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 ber for the curr
cb80: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d ent date and tim
cb90: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 e as.** a floati
cba0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a ng point value..
cbb0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 ** ^The xCurrent
cbc0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 TimeInt64() meth
cbd0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 od returns, as a
cbe0: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a n integer, the J
cbf0: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d ulian.** Day Num
cc00: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 ber multiplied b
cc10: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 y 86400000 (the
cc20: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 number of millis
cc30: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 econds in .** a
cc40: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 24-hour day). .
cc50: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
cc60: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 use the xCurrent
cc70: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 TimeInt64() meth
cc80: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 od to get the cu
cc90: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e rrent.** date an
cca0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d d time if that m
ccb0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 ethod is availab
ccc0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 le (if iVersion
ccd0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 is 2 or .** grea
cce0: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 ter and the func
ccf0: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
cd00: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 not NULL) and wi
cd10: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 ll fall back.**
cd20: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 to xCurrentTime(
cd30: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d ) if xCurrentTim
cd40: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 eInt64() is unav
cd50: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e ailable..**.** ^
cd60: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 The xSetSystemCa
cd70: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d ll(), xGetSystem
cd80: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 Call(), and xNes
cd90: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e tSystemCall() in
cda0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 terfaces.** are
cdb0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 not used by the
cdc0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 SQLite core. Th
cdd0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 ese optional int
cde0: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 erfaces are prov
cdf0: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 ided.** by some
ce00: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 VFSes to facilit
ce10: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 ate testing of t
ce20: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 he VFS code. By
ce30: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 overriding .** s
ce40: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 ystem calls with
ce50: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 functions under
ce60: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 its control, a
ce70: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e test program can
ce80: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 .** simulate fau
ce90: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f lts and error co
cea0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f nditions that wo
ceb0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 uld otherwise be
cec0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 difficult.** or
ced0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 impossible to i
cee0: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 nduce. The set
cef0: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 of system calls
cf00: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 that can be over
cf10: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 ridden.** varies
cf20: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f from one VFS to
cf30: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 another, and fr
cf40: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f om one version o
cf50: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 f the same VFS t
cf60: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 o the.** next.
cf70: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
cf80: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 t use these inte
cf90: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 rfaces must be p
cfa0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a repared for any.
cfb0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 ** or all of the
cfc0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f se interfaces to
cfd0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 be NULL or for
cfe0: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 their behavior t
cff0: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d o change.** from
d000: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 one release to
d010: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 the next. Appli
d020: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 cations must not
d030: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 attempt to acce
d040: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 ss.** any of the
d050: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 se methods if th
d060: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 e iVersion of th
d070: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 e VFS is less th
d080: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 an 3..*/.typedef
d090: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
d0a0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b vfs sqlite3_vfs;
d0b0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
d0c0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
d0d0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 ptr)(void);.stru
d0e0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b ct sqlite3_vfs {
d0f0: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
d100: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 /* S
d110: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e tructure version
d120: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 number (current
d130: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 ly 3) */. int s
d140: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 zOsFile;
d150: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 /* Size of s
d160: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 ubclassed sqlite
d170: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 3_file */. int
d180: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 mxPathname;
d190: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
d1a0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 file pathname le
d1b0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 ngth */. sqlite
d1c0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 3_vfs *pNext;
d1d0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 /* Next regis
d1e0: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 tered VFS */. c
d1f0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
d200: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 ; /* Name
d210: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 of this virtual
d220: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 file system */.
d230: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
d240: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 /* Poi
d250: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 nter to applicat
d260: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 ion-specific dat
d270: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 a */. int (*xOp
d280: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a en)(sqlite3_vfs*
d290: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
d2a0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c ame, sqlite3_fil
d2b0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 e*,.
d2c0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e int flags, in
d2d0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 t *pOutFlags);.
d2e0: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 int (*xDelete)(
d2f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
d300: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
d310: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 int syncDir);.
d320: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 int (*xAccess)(
d330: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
d340: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
d350: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
d360: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
d370: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 (*xFullPathname
d380: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
d390: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
d3a0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 e, int nOut, cha
d3b0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 r *zOut);. void
d3c0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c *(*xDlOpen)(sql
d3d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
d3e0: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 char *zFilename
d3f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 );. void (*xDlE
d400: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 rror)(sqlite3_vf
d410: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
d420: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 har *zErrMsg);.
d430: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d void (*(*xDlSym
d440: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 )(sqlite3_vfs*,v
d450: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 oid*, const char
d460: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 *zSymbol))(void
d470: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 );. void (*xDlC
d480: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 lose)(sqlite3_vf
d490: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e s*, void*);. in
d4a0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 t (*xRandomness)
d4b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
d4c0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
d4d0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 zOut);. int (*x
d4e0: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 Sleep)(sqlite3_v
d4f0: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 fs*, int microse
d500: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a conds);. int (*
d510: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 xCurrentTime)(sq
d520: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 lite3_vfs*, doub
d530: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 le*);. int (*xG
d540: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c etLastError)(sql
d550: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 ite3_vfs*, int,
d560: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 char *);. /*.
d570: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 ** The methods a
d580: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 bove are in vers
d590: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c ion 1 of the sql
d5a0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 ite_vfs object.
d5b0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 ** definition.
d5c0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c Those that foll
d5d0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 ow are added in
d5e0: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 version 2 or lat
d5f0: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a er. */. int (*
d600: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
d610: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 4)(sqlite3_vfs*,
d620: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 sqlite3_int64*)
d630: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 ;. /*. ** The
d640: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 methods above ar
d650: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 e in versions 1
d660: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c and 2 of the sql
d670: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a ite_vfs object..
d680: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 ** Those below
d690: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e are for version
d6a0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 3 and greater..
d6b0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 */. int (*xSe
d6c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c tSystemCall)(sql
d6d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
d6e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 char *zName, sq
d6f0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 lite3_syscall_pt
d700: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 r);. sqlite3_sy
d710: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 scall_ptr (*xGet
d720: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 SystemCall)(sqli
d730: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
d740: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 char *zName);.
d750: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e const char *(*xN
d760: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 extSystemCall)(s
d770: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
d780: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
d790: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d . /*. ** The m
d7a0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
d7b0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 in versions 1 t
d7c0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 hrough 3 of the
d7d0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
d7e0: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c t.. ** New fiel
d7f0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ds may be append
d800: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 ed in figure ver
d810: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 sions. The iVer
d820: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 sion. ** value
d830: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 will increment w
d840: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 henever this hap
d850: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a pens. . */.};..
d860: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
d870: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 Flags for the xA
d880: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 ccess VFS method
d890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
d8a0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 eger constants c
d8b0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 an be used as th
d8c0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
d8d0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 r to.** the xAcc
d8e0: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e ess method of an
d8f0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f [sqlite3_vfs] o
d900: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 bject. They det
d910: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b ermine.** what k
d920: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f ind of permissio
d930: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ns the xAccess m
d940: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 ethod is looking
d950: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 for..** With SQ
d960: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
d970: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TS, the xAccess
d980: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 method.** simply
d990: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
d9a0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e the file exists.
d9b0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
d9c0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 ACCESS_READWRITE
d9d0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
d9e0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
d9f0: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 hether the named
da00: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f directory is bo
da10: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 th readable and
da20: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 writable.** (in
da30: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 other words, if
da40: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 files can be add
da50: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 ed, removed, and
da60: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a renamed within.
da70: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 ** the directory
da80: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 )..** The SQLITE
da90: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 _ACCESS_READWRIT
daa0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 E constant is cu
dab0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c rrently used onl
dac0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d y by the.** [tem
dad0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
dae0: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 y pragma], thoug
daf0: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 h this could cha
db00: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a nge in a future.
db10: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ** release of SQ
db20: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 Lite..** With SQ
db30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
db40: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
db50: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 thod.** checks w
db60: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 hether the file
db70: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 is readable. Th
db80: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
db90: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 READ constant is
dba0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e .** currently un
dbb0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 used, though it
dbc0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e might be used in
dbd0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 a future releas
dbe0: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a e of.** SQLite..
dbf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
dc00: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 E_ACCESS_EXISTS
dc10: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
dc20: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
dc30: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 RITE 1 /* Used
dc40: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f by PRAGMA temp_
dc50: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
dc60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
dc70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 E_ACCESS_READ
dc80: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 2 /* Unused
dc90: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
dca0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
dcb0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 he xShmLock VFS
dcc0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 method.**.** The
dcd0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
dce0: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 ants define the
dcf0: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 various locking
dd00: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c operations.** al
dd10: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 lowed by the xSh
dd20: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 mLock method of
dd30: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
dd40: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f ods]. The.** fo
dd50: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 llowing are the
dd60: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 only legal combi
dd70: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 nations of flags
dd80: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c to the.** xShmL
dd90: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a ock method:.**.*
dda0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
ddb0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
ddc0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 | SQLITE_SHM_SHA
ddd0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c RED.** <li> SQL
dde0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 ITE_SHM_LOCK | S
ddf0: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 QLITE_SHM_EXCLUS
de00: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c IVE.** <li> SQL
de10: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c ITE_SHM_UNLOCK |
de20: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 SQLITE_SHM_SHAR
de30: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 ED.** <li> SQLI
de40: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 TE_SHM_UNLOCK |
de50: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 SQLITE_SHM_EXCLU
de60: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a SIVE.** </ul>.**
de70: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 .** When unlocki
de80: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 ng, the same SHA
de90: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 RED or EXCLUSIVE
dea0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 flag must be su
deb0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 pplied as.** was
dec0: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f given no the co
ded0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b rresponding lock
dee0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 . .**.** The xS
def0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 hmLock method ca
df00: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 n transition bet
df10: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e ween unlocked an
df20: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 d SHARED or.** b
df30: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 etween unlocked
df40: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 and EXCLUSIVE.
df50: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 It cannot transi
df60: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 tion between SHA
df70: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 RED.** and EXCLU
df80: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 SIVE..*/.#define
df90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
dfa0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 CK 1.#defi
dfb0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f ne SQLITE_SHM_LO
dfc0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 CK 2.#de
dfd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
dfe0: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 SHARED 4.#
dff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
e000: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 M_EXCLUSIVE 8
e010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
e020: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f : Maximum xShmLo
e030: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 ck index.**.** T
e040: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
e050: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 od on [sqlite3_i
e060: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 o_methods] may u
e070: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 se values.** bet
e080: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 ween 0 and this
e090: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 upper bound as i
e0a0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 ts "offset" argu
e0b0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c ment..** The SQL
e0c0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 ite core will ne
e0d0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 ver attempt to a
e0e0: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 cquire or releas
e0f0: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 e a.** lock outs
e100: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 ide of this rang
e110: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e.*/.#define SQL
e120: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 ITE_SHM_NLOCK
e130: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 8.../*.** C
e140: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c API3REF: Initial
e150: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c ize The SQLite L
e160: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 ibrary.**.** ^Th
e170: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
e180: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 lize() routine i
e190: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a nitializes the.*
e1a0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 * SQLite library
e1b0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
e1c0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 shutdown() routi
e1d0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 ne.** deallocate
e1e0: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 s any resources
e1f0: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 that were alloca
e200: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 ted by sqlite3_i
e210: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 nitialize()..**
e220: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
e230: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 re designed to a
e240: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e id in process in
e250: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
e260: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 .** shutdown on
e270: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 embedded systems
e280: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 . Workstation a
e290: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e pplications usin
e2a0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d g.** SQLite norm
e2b0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 ally do not need
e2c0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 to invoke eithe
e2d0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 r of these routi
e2e0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c nes..**.** A cal
e2f0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 l to sqlite3_ini
e300: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 tialize() is an
e310: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
e320: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 if it is.** the
e330: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
e340: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
e350: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 is invoked duri
e360: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 ng the lifetime
e370: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 of.** the proces
e380: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 s, or if it is t
e390: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
e3a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
e3b0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a () is invoked.**
e3c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c following a cal
e3d0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
e3e0: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 tdown(). ^(Only
e3f0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
e400: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 ll.** of sqlite3
e410: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f _initialize() do
e420: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a es any initializ
e430: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 ation. All othe
e440: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 r calls.** are h
e450: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 armless no-ops.)
e460: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 ^.**.** A call t
e470: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
e480: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 wn() is an "effe
e490: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
e4a0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a t is the first.*
e4b0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 * call to sqlite
e4c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 3_shutdown() sin
e4d0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 ce the last sqli
e4e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
e4f0: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 . ^(Only.** an
e500: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 effective call t
e510: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f o sqlite3_shutdo
e520: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 wn() does any de
e530: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a initialization..
e540: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c ** All other val
e550: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 id calls to sqli
e560: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 te3_shutdown() a
e570: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
e580: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ps.)^.**.** The
e590: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e5a0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ze() interface i
e5b0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 s threadsafe, bu
e5c0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f t sqlite3_shutdo
e5d0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 wn().** is not.
e5e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 The sqlite3_shu
e5f0: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 tdown() interfac
e600: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 e must only be c
e610: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 alled from a.**
e620: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
e630: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 All open [databa
e640: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
e650: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 must be closed a
e660: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 nd all.** other
e670: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 SQLite resources
e680: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 must be dealloc
e690: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e ated prior to in
e6a0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 voking.** sqlite
e6b0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 3_shutdown()..**
e6c0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 .** Among other
e6d0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 things, ^sqlite3
e6e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 _initialize() wi
e6f0: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c ll invoke.** sql
e700: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
e710: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c Similarly, ^sql
e720: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
e730: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 ** will invoke s
e740: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e qlite3_os_end().
e750: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
e760: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
e770: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
e780: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 [SQLITE_OK] on
e790: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 success..** ^If
e7a0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c for some reason,
e7b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
e7c0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 ize() is unable
e7d0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a to initialize.**
e7e0: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 the library (pe
e7f0: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 rhaps it is unab
e800: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 le to allocate a
e810: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 needed resource
e820: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 such.** as a mu
e830: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 tex) it returns
e840: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
e850: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
e860: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 TE_OK]..**.** ^T
e870: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
e880: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 alize() routine
e890: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e is called intern
e8a0: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 ally by many oth
e8b0: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 er.** SQLite int
e8c0: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 erfaces so that
e8d0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 an application u
e8e0: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 sually does not
e8f0: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b need to.** invok
e900: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
e910: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e lize() directly.
e920: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b For example, [
e930: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a sqlite3_open()].
e940: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 ** calls sqlite3
e950: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f _initialize() so
e960: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
e970: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ary will be auto
e980: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 matically.** ini
e990: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 tialized when [s
e9a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 qlite3_open()] i
e9b0: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 s called if it h
e9c0: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 as not be initia
e9d0: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 lized.** already
e9e0: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 . ^However, if
e9f0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
ea00: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ed with the [SQL
ea10: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
ea20: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 T].** compile-ti
ea30: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 me option, then
ea40: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 the automatic ca
ea50: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 lls to sqlite3_i
ea60: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 nitialize().** a
ea70: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 re omitted and t
ea80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
ea90: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 ust call sqlite3
eaa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 _initialize() di
eab0: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 rectly.** prior
eac0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
ead0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
eae0: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 ace. For maximu
eaf0: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a m portability,.*
eb00: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e * it is recommen
eb10: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
eb20: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 tions always inv
eb30: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
eb40: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 ialize().** dire
eb50: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 ctly prior to us
eb60: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
eb70: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
eb80: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 Future releases
eb90: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 .** of SQLite ma
eba0: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 y require this.
ebb0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
ebc0: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 the behavior ex
ebd0: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 hibited.** when
ebe0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
ebf0: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
ec00: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d OMIT_AUTOINIT] m
ec10: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a ight become the.
ec20: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 ** default behav
ec30: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ior in some futu
ec40: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 re release of SQ
ec50: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Lite..**.** The
ec60: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
ec70: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f ) routine does o
ec80: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
ec90: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 specific.** init
eca0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 ialization of th
ecb0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 e SQLite library
ecc0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f . The sqlite3_o
ecd0: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 s_end().** routi
ece0: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 ne undoes the ef
ecf0: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f fect of sqlite3_
ed00: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 os_init(). Typi
ed10: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 cal tasks.** per
ed20: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 formed by these
ed30: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 routines include
ed40: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 allocation or d
ed50: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
ed60: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 f static resourc
ed70: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 es, initializati
ed80: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 on of global var
ed90: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 iables,.** setti
eda0: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 ng up a default
edb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f [sqlite3_vfs] mo
edc0: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 dule, or setting
edd0: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 up.** a default
ede0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
edf0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f sing [sqlite3_co
ee00: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 nfig()]..**.** T
ee10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 he application s
ee20: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f hould never invo
ee30: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 ke either sqlite
ee40: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 3_os_init().** o
ee50: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
ee60: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 () directly. Th
ee70: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
ee80: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 ould only invoke
ee90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 .** sqlite3_init
eea0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c ialize() and sql
eeb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
eec0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 The sqlite3_os
eed0: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 _init().** inter
eee0: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 face is called a
eef0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
ef00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ef10: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 ze() and.** sqli
ef20: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 te3_os_end() is
ef30: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 called by sqlite
ef40: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 3_shutdown(). A
ef50: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d ppropriate.** im
ef60: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f plementations fo
ef70: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 r sqlite3_os_ini
ef80: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
ef90: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 os_end().** are
efa0: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
efb0: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d e when it is com
efc0: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 piled for Unix,
efd0: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 Windows, or OS/2
efe0: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f ..** When [custo
eff0: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 m builds | built
f000: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 for other platf
f010: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 orms].** (using
f020: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f the [SQLITE_OS_O
f030: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d THER=1] compile-
f040: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 time.** option)
f050: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
f060: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 must supply a su
f070: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 itable implement
f080: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c ation for.** sql
f090: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
f0a0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
f0b0: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 d(). An applica
f0c0: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a tion-supplied.**
f0d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
f0e0: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
f0f0: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f it() or sqlite3_
f100: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 os_end().** must
f110: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
f120: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 OK] on success a
f130: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 nd some other [e
f140: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a rror code] upon.
f150: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 ** failure..*/.i
f160: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 nt sqlite3_initi
f170: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 alize(void);.int
f180: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f190: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c n(void);.int sql
f1a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 ite3_os_init(voi
f1b0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
f1c0: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
f1d0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
f1e0: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
f1f0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
f200: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
f210: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
f220: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
f230: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
f240: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
f250: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
f260: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
f270: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
f280: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
f290: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
f2a0: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
f2b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
f2c0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
f2d0: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
f2e0: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
f2f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
f300: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
f310: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
f320: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
f330: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
f340: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
f350: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 needs..**.** The
f360: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
f370: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
f380: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 ot threadsafe.
f390: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a The application.
f3a0: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 ** must insure t
f3b0: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c hat no other SQL
f3c0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
f3d0: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 re invoked by ot
f3e0: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 her.** threads w
f3f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e hile sqlite3_con
f400: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 fig() is running
f410: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 . Furthermore,
f420: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f430: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
f440: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f invoked prior to
f450: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c library initial
f460: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a ization using.**
f470: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
f480: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
f490: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 shutdown by [sq
f4a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f4b0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
f4c0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 3_config() is ca
f4d0: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
f4e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f4f0: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 ] and before.**
f500: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
f510: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c n()] then it wil
f520: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f l return SQLITE_
f530: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c MISUSE..** Note,
f540: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e however, that ^
f550: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f560: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
f570: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
f580: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
f590: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
f5a0: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
f5b0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
f5c0: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
f5d0: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
f5e0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
f5f0: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f n integer.** [co
f600: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
f610: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 on] that determi
f620: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 nes.** what prop
f630: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 erty of SQLite i
f640: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 s to be configur
f650: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 ed. Subsequent
f660: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 arguments.** var
f670: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 y depending on t
f680: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f he [configuratio
f690: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
f6a0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
f6b0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
f6c0: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
f6d0: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
f6e0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
f6f0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
f700: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
f710: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
f720: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
f730: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
f740: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
f750: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
f760: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
f770: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
f780: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e .int sqlite3_con
f790: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a fig(int, ...);..
f7a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
f7b0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 Configure databa
f7c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a se connections.*
f7d0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
f7e0: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 _db_config() int
f7f0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
f800: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 o make configura
f810: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
f820: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 to a [database c
f830: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
f840: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 interface is si
f850: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c milar to.** [sql
f860: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 ite3_config()] e
f870: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 xcept that the c
f880: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 hanges apply to
f890: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 a single.** [dat
f8a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
f8b0: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 ] (specified in
f8c0: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
f8d0: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nt)..**.** The s
f8e0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
f8f0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
f900: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 fig(D,V,...) is
f910: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
f920: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
f930: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 DE | configurati
f940: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e on verb] - an in
f950: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 teger code .** t
f960: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 hat indicates wh
f970: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 at aspect of the
f980: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
f990: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
f9a0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 configured..** S
f9b0: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
f9c0: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 nts vary dependi
f9d0: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 ng on the config
f9e0: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a uration verb..**
f9f0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 .** ^Calls to sq
fa00: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
fa10: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
fa20: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 OK if and only i
fa30: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 f.** the call is
fa40: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 considered succ
fa50: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 essful..*/.int s
fa60: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
fa70: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
fa80: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 p, ...);../*.**
fa90: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
faa0: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 Allocation Rout
fab0: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e ines.**.** An in
fac0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
fad0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
fae0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
faf0: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e een SQLite.** an
fb00: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f d low-level memo
fb10: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
fb20: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
fb30: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 is object is use
fb40: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c d in only one pl
fb50: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 ace in the SQLit
fb60: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 e interface..**
fb70: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
fb80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
fb90: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 object is the a
fba0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 rgument to.** [s
fbb0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
fbc0: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 when the config
fbd0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
fbe0: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e s.** [SQLITE_CON
fbf0: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b FIG_MALLOC] or [
fc00: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
fc10: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 TMALLOC]. .** B
fc20: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e y creating an in
fc30: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
fc40: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 bject.** and pas
fc50: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
fc60: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
fc70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
fc80: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f C]).** during co
fc90: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 nfiguration, an
fca0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 application can
fcb0: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
fcc0: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
fcd0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
fce0: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 ystem for SQLite
fcf0: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 to use for all
fd00: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 of its.** dynami
fd10: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a c memory needs..
fd20: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
fd30: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 SQLite comes wit
fd40: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 h several [built
fd50: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
fd60: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 ators].** that a
fd70: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 re perfectly ade
fd80: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 quate for the ov
fd90: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 erwhelming major
fda0: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
fdb0: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ons.** and that
fdc0: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f this object is o
fdd0: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 nly useful to a
fde0: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 tiny minority of
fdf0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
fe00: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 with specialize
fe10: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
fe20: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 ion requirements
fe30: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 . This object i
fe40: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 s.** also used d
fe50: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 uring testing of
fe60: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
fe70: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 to specify an a
fe80: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
fe90: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 mory allocator t
fea0: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 hat simulates me
feb0: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f mory out-of-memo
fec0: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e ry conditions in
fed0: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 .** order to ver
fee0: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 ify that SQLite
fef0: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 recovers gracefu
ff00: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a lly from such.**
ff10: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a conditions..**.
ff20: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 ** The xMalloc,
ff30: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 xRealloc, and xF
ff40: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 ree methods must
ff50: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a work like the.*
ff60: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c * malloc(), real
ff70: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
ff80: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 functions from
ff90: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
ffa0: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 ibrary..** ^SQLi
ffb0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
ffc0: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 at the second ar
ffd0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 gument to.** xRe
ffe0: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 alloc is always
fff0: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 a value returned
10000 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c by a prior call
10010 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a to xRoundup..**
10020 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 .** xSize should
10030 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f return the allo
10040 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 cated size of a
10050 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
10060 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 n.** previously
10070 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d obtained from xM
10080 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f alloc or xReallo
10090 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 c. The allocate
100a0 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 d size.** is alw
100b0 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 ays at least as
100c0 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 big as the reque
100d0 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 sted size but ma
100e0 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a y be larger..**.
100f0 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 ** The xRoundup
10100 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 method returns w
10110 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 hat would be the
10120 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 allocated size
10130 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 of.** a memory a
10140 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 llocation given
10150 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 a particular req
10160 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f uested size. Mo
10170 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c st memory.** all
10180 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
10190 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
101a0 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 ons at least to
101b0 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c the next multipl
101c0 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 e.** of 8. Some
101d0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
101e0 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 d up to a larger
101f0 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 multiple or to
10200 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a a power of 2..**
10210 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c Every memory al
10220 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 location request
10230 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 coming in throu
10240 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c gh [sqlite3_mall
10250 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c oc()].** or [sql
10260 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
10270 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 first calls xRou
10280 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 ndup. If xRound
10290 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a up returns 0, .*
102a0 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 * that causes th
102b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
102c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
102d0 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a n to fail..**.**
102e0 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f The xInit metho
102f0 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 d initializes th
10300 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
10310 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c or. (For exampl
10320 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 e,.** it might a
10330 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 llocate any requ
10340 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 ire mutexes or i
10350 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e nitialize intern
10360 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 al data.** struc
10370 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 tures. The xShu
10380 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 tdown method is
10390 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 invoked (indirec
103a0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 tly) by.** [sqli
103b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
103c0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c and should deall
103d0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 ocate any resour
103e0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 ces acquired.**
103f0 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 by xInit. The p
10400 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 AppData pointer
10410 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f is used as the o
10420 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f nly parameter to
10430 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 .** xInit and xS
10440 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 hutdown..**.** S
10450 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 QLite holds the
10460 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
10470 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 ATIC_MASTER] mut
10480 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b ex when it invok
10490 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 es.** the xInit
104a0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 method, so the x
104b0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 Init method need
104c0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 not be threadsa
104d0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 fe. The.** xShu
104e0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 tdown method is
104f0 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d only called from
10500 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
10510 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 wn()] so it does
10520 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 .** not need to
10530 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 be threadsafe ei
10540 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f ther. For all o
10550 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 ther methods, SQ
10560 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 Lite.** holds th
10570 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f e [SQLITE_MUTEX_
10580 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 STATIC_MEM] mute
10590 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 x as long as the
105a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
105b0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f IG_MEMSTATUS] co
105c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
105d0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 on is turned on
105e0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 (which.** it is
105f0 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 by default) and
10600 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 so the methods a
10610 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 re automatically
10620 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 serialized..**
10630 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c However, if [SQL
10640 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
10650 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 ATUS] is disable
10660 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 d, then the othe
10670 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 r.** methods mus
10680 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 t be threadsafe
10690 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 or else make the
106a0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 ir own arrangeme
106b0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 nts for.** seria
106c0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 lization..**.**
106d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 SQLite will neve
106e0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 r invoke xInit()
106f0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 more than once
10700 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 without an inter
10710 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 vening.** call t
10720 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a o xShutdown()..*
10730 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
10740 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
10750 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d hods sqlite3_mem
10760 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 _methods;.struct
10770 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
10780 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 hods {. void *(
10790 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 *xMalloc)(int);
107a0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 /* Memor
107b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e y allocation fun
107c0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ction */. void
107d0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b (*xFree)(void*);
107e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 /* Fre
107f0 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 e a prior alloca
10800 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
10810 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 (*xRealloc)(void
10820 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 *,int); /* Resi
10830 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e ze an allocation
10840 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a */. int (*xSiz
10850 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
10860 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 /* Return t
10870 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c he size of an al
10880 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e location */. in
10890 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e t (*xRoundup)(in
108a0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 t); /*
108b0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 Round up request
108c0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 size to allocat
108d0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e ion size */. in
108e0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a t (*xInit)(void*
108f0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ); /*
10900 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d Initialize the m
10910 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
10920 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 */. void (*xShu
10930 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 tdown)(void*);
10940 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c /* Deinitial
10950 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 ize the memory a
10960 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f llocator */. vo
10970 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 id *pAppData;
10980 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
10990 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 Argument to xIni
109a0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 t() and xShutdow
109b0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a n() */.};../*.**
109c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
109d0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 guration Options
109e0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 .** KEYWORDS: {c
109f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
10a00 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ion}.**.** These
10a10 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 constants are t
10a20 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 he available int
10a30 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 eger configurati
10a40 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a on options that.
10a50 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 ** can be passed
10a60 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
10a70 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
10a80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
10a90 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
10aa0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 * New configurat
10ab0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 ion options may
10ac0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
10ad0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
10ae0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 QLite..** Existi
10af0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
10b00 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 options might b
10b10 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 e discontinued.
10b20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a Applications.**
10b30 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 should check th
10b40 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 e return code fr
10b50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 om [sqlite3_conf
10b60 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
10b70 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
10b80 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 all worked. The
10b90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
10ba0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
10bb0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
10bc0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
10bd0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
10be0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
10bf0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
10c00 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
10c10 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
10c20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
10c30 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
10c40 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
10c50 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
10c60 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 HREAD</dt>.** <d
10c70 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 d>There are no a
10c80 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
10c90 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 option. ^This
10ca0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a option sets the.
10cb0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ** [threading mo
10cc0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 de] to Single-th
10cd0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 read. In other
10ce0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c words, it disabl
10cf0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 es.** all mutexi
10d00 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 ng and puts SQLi
10d10 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 te into a mode w
10d20 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 here it can only
10d30 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 be used.** by a
10d40 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 single thread.
10d50 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
10d60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
10d70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
10d80 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
10d90 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
10da0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
10db0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
10dc0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
10dd0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 change the [thr
10de0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f eading mode] fro
10df0 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a m its default.**
10e00 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 value of Single
10e10 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b -thread and so [
10e20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
10e30 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a ] will return .*
10e40 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d * [SQLITE_ERROR]
10e50 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
10e60 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
10e70 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a G_SINGLETHREAD.*
10e80 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
10e90 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
10ea0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
10eb0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d IG_MULTITHREAD]]
10ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
10ed0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f IG_MULTITHREAD</
10ee0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
10ef0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
10f00 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
10f10 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
10f20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
10f30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
10f40 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 Multi-thread. I
10f50 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 n other words, i
10f60 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 t disables.** mu
10f70 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 texing on [datab
10f80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10f90 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
10fa0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
10fb0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
10fc0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 tion is responsi
10fd0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a ble for serializ
10fe0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a ing access to.**
10ff0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11000 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 ctions] and [pre
11010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
11020 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 ]. But other mu
11030 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
11040 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c bled so that SQL
11050 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 ite will be safe
11060 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c to use in a mul
11070 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 ti-threaded.** e
11080 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f nvironment as lo
11090 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 ng as no two thr
110a0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 eads attempt to
110b0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 use the same.**
110c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
110d0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d tion] at the sam
110e0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c e time. ^If SQL
110f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
11100 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
11110 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
11120 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
11130 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
11140 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
11150 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 * it is not poss
11160 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 ible to set the
11170 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 Multi-thread [th
11180 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e reading mode] an
11190 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
111a0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
111b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
111c0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
111d0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
111e0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
111f0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e AD configuration
11200 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
11210 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
11220 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d FIG_SERIALIZED]]
11230 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
11240 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 IG_SERIALIZED</d
11250 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
11260 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
11270 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
11280 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
11290 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
112a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 ading mode] to S
112b0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 erialized. In ot
112c0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 her words, this
112d0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a option enables.*
112e0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e * all mutexes in
112f0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 cluding the recu
11300 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 rsive.** mutexes
11310 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
11320 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
11330 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11340 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 t] objects..** I
11350 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 n this mode (whi
11360 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c ch is the defaul
11370 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 t when SQLite is
11380 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
11390 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
113a0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c SAFE=1]) the SQL
113b0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c ite library will
113c0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a itself serializ
113d0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b e access.** to [
113e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
113f0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
11400 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 red statements]
11410 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 so that the.** a
11420 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 pplication is fr
11430 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 ee to use the sa
11440 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e me [database con
11450 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a nection] or the.
11460 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 ** same [prepare
11470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 d statement] in
11480 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 different thread
11490 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 s at the same ti
114a0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 me..** ^If SQLit
114b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
114c0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
114d0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
114e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
114f0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
11500 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
11510 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
11520 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 le to set the Se
11530 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
11540 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a ing mode] and.**
11550 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
11560 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ()] will return
11570 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
11580 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
11590 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 e.** SQLITE_CONF
115a0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f IG_SERIALIZED co
115b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
115c0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
115d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
115e0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 ALLOC]] <dt>SQLI
115f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
11600 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
11610 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
11620 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
11630 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
11640 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
11650 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
11660 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
11670 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
11680 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 The argument s
11690 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 pecifies.** alte
116a0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 rnative low-leve
116b0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
116c0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ion routines to
116d0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 be used in place
116e0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 of.** the memor
116f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
11700 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
11710 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 SQLite.)^ ^SQLi
11720 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 te makes.** its
11730 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
11740 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 of the content
11750 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
11760 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
11770 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 ucture.** before
11780 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
11790 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 nfig()] call ret
117a0 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a urns.</dd>.**.**
117b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
117c0 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 _GETMALLOC]] <dt
117d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
117e0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a ETMALLOC</dt>.**
117f0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
11800 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
11810 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
11820 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
11830 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 o an.** instance
11840 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
11850 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
11860 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 ructure. The [s
11870 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11880 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
11890 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
118a0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
118b0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c fined memory all
118c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
118d0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 .)^.** This opti
118e0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
118f0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
11900 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c efault memory al
11910 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 location.** rout
11920 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 ines with a wrap
11930 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 per that simulat
11940 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ions memory allo
11950 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f cation failure o
11960 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f r.** tracks memo
11970 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 ry usage, for ex
11980 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a ample. </dd>.**.
11990 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
119a0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c IG_MEMSTATUS]] <
119b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
119c0 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a _MEMSTATUS</dt>.
119d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
119e0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c tion takes singl
119f0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 e argument of ty
11a00 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 pe int, interpre
11a10 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f ted as a .** boo
11a20 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
11a30 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
11a40 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
11a50 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 f memory allocat
11a60 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 ion .** statisti
11a70 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
11a80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
11a90 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 tistics are disa
11aa0 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f bled, the .** fo
11ab0 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 llowing SQLite i
11ac0 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 nterfaces become
11ad0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c non-operational
11ae0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 :.** <ul>.**
11af0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
11b00 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a emory_used()].**
11b10 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
11b20 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
11b30 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b r()].** <li> [
11b40 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 sqlite3_soft_hea
11b50 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 p_limit64()].**
11b60 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
11b70 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c status()].** <
11b80 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 /ul>)^.** ^Memor
11b90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
11ba0 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 tistics are enab
11bb0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 led by default u
11bc0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a nless SQLite is.
11bd0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
11be0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
11bf0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e _MEMSTATUS]=0 in
11c00 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f which case memo
11c10 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
11c20 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
11c30 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
11c40 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ult..** </dd>.**
11c50 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
11c60 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 FIG_SCRATCH]] <d
11c70 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
11c80 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 SCRATCH</dt>.**
11c90 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
11ca0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
11cb0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
11cc0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
11cd0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 an use for.** sc
11ce0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 ratch memory. T
11cf0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
11d00 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 rguments: A poi
11d10 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a nter an 8-byte.*
11d20 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 * aligned memory
11d30 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 buffer from whi
11d40 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 ch the scratch a
11d50 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 llocations will
11d60 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 be.** drawn, the
11d70 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 size of each sc
11d80 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
11d90 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 (sz),.** and th
11da0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
11db0 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f of scratch allo
11dc0 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 cations (N). Th
11dd0 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 e sz.** argument
11de0 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 must be a multi
11df0 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 ple of 16..** Th
11e00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
11e10 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 must be a point
11e20 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 er to an 8-byte
11e30 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a aligned buffer.*
11e40 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a * of at least sz
11e50 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f *N bytes of memo
11e60 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ry..** ^SQLite w
11e70 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 ill use no more
11e80 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68 than two scratch
11e90 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 buffers per thr
11ea0 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 ead. So.** N sh
11eb0 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 ould be set to t
11ec0 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65 wice the expecte
11ed0 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 d maximum number
11ee0 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 of threads..**
11ef0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 ^SQLite will nev
11f00 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 er require a scr
11f10 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 atch buffer that
11f20 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a is more than 6.
11f30 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 ** times the dat
11f40 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e abase page size.
11f50 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 ^If SQLite need
11f60 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e s needs addition
11f70 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 al.** scratch me
11f80 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 mory beyond what
11f90 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
11fa0 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 this configurati
11fb0 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 on option, then
11fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
11fd0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 loc()] will be u
11fe0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
11ff0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e e memory needed.
12000 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
12010 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
12020 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 CACHE]] <dt>SQLI
12030 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
12040 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
12050 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 ^This option sp
12060 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
12070 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 memory buffer t
12080 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
12090 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 se for.** the da
120a0 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 tabase page cach
120b0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 e with the defau
120c0 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d lt page cache im
120d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a plementation. .
120e0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
120f0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 ation should not
12100 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 be used if an a
12110 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
12120 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
12130 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
12140 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
12150 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
12160 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e _PCACHE2 option.
12170 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 .** There are th
12180 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
12190 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 this option: A
121a0 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 pointer to 8-byt
121b0 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d e aligned.** mem
121c0 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 ory, the size of
121d0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 each page buffe
121e0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 r (sz), and the
121f0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 number of pages
12200 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 (N)..** The sz a
12210 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 rgument should b
12220 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 e the size of th
12230 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 e largest databa
12240 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f se page.** (a po
12250 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 wer of two betwe
12260 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38 en 512 and 32768
12270 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 ) plus a little
12280 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a extra for each.*
12290 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 * page header.
122a0 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72 ^The page header
122b0 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34 size is 20 to 4
122c0 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e 0 bytes dependin
122d0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 g on.** the host
122e0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20 architecture.
122f0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c ^It is harmless,
12300 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 apart from the
12310 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a wasted memory,.*
12320 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c * to make sz a l
12330 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e ittle too large.
12340 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 The first.** a
12350 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 rgument should p
12360 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 oint to an alloc
12370 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 ation of at leas
12380 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
12390 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
123a0 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 te will use the
123b0 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20 memory provided
123c0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 by the first arg
123d0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79 ument to satisfy
123e0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e its.** memory n
123f0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72 eeds for the fir
12400 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20 st N pages that
12410 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65 it adds to cache
12420 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 . ^If additiona
12430 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 l.** page cache
12440 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 memory is needed
12450 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 beyond what is
12460 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 provided by this
12470 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a option, then.**
12480 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 SQLite goes to
12490 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
124a0 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74 )] for the addit
124b0 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70 ional storage sp
124c0 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e ace..** The poin
124d0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 ter in the first
124e0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a argument must.*
124f0 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 * be aligned to
12500 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 an 8-byte bounda
12510 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 ry or subsequent
12520 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c behavior of SQL
12530 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 ite.** will be u
12540 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a ndefined.</dd>.*
12550 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
12560 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e NFIG_HEAP]] <dt>
12570 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
12580 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 AP</dt>.** <dd>
12590 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
125a0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
125b0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
125c0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 at SQLite will u
125d0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 se.** for all of
125e0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d its dynamic mem
125f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e ory allocation n
12600 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 eeds beyond thos
12610 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f e provided.** fo
12620 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e r by [SQLITE_CON
12630 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 FIG_SCRATCH] and
12640 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
12650 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 PAGECACHE]..** T
12660 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
12670 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 rguments: An 8-b
12680 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e yte aligned poin
12690 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 ter to the memor
126a0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 y,.** the number
126b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
126c0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 memory buffer,
126d0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 and the minimum
126e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e allocation size.
126f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 .** ^If the firs
12700 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
12710 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 emory pointer) i
12720 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c s NULL, then SQL
12730 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 ite reverts.** t
12740 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 o using its defa
12750 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
12760 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d ator (the system
12770 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d malloc() implem
12780 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e entation),.** un
12790 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 doing any prior
127a0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 invocation of [S
127b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
127c0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a LOC]. ^If the.*
127d0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 * memory pointer
127e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
127f0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f either [SQLITE_
12800 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 ENABLE_MEMSYS3]
12810 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e or.** [SQLITE_EN
12820 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 ABLE_MEMSYS5] ar
12830 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 e defined, then
12840 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 the alternative
12850 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
12860 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 tor is engaged t
12870 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 o handle all of
12880 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 SQLites memory a
12890 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e llocation needs.
128a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f .** The first po
128b0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
128c0 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 y pointer) must
128d0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
128e0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 8-byte.** bound
128f0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e ary or subsequen
12900 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 t behavior of SQ
12910 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 Lite will be und
12920 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d efined..** The m
12930 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f inimum allocatio
12940 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 n size is capped
12950 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f at 2**12. Reaso
12960 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 nable values.**
12970 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 for the minimum
12980 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 allocation size
12990 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 are 2**5 through
129a0 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2**8.</dd>.**.*
129b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
129c0 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 G_MUTEX]] <dt>SQ
129d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
129e0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
129f0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
12a00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
12a10 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
12a20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
12a30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
12a40 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
12a50 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
12a60 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e re. The argumen
12a70 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 t specifies.** a
12a80 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
12a90 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
12aa0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 nes to be used i
12ab0 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d n place.** the m
12ac0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
12ad0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
12ae0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 )^ ^SQLite make
12af0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
12b00 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 ** content of th
12b10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
12b20 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
12b30 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 ure before the c
12b40 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
12b50 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 e3_config()] ret
12b60 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 urns. ^If SQLite
12b70 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
12b80 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
12b90 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
12ba0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
12bb0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
12bc0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
12bd0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
12be0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
12bf0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
12c00 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
12c10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
12c20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
12c30 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
12c40 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e CONFIG_MUTEX con
12c50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12c60 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
12c70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
12c80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
12c90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
12ca0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
12cb0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
12cc0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
12cd0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
12ce0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
12cf0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
12d00 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
12d10 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
12d20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
12d30 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
12d40 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
12d50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
12d60 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
12d70 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
12d80 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
12d90 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
12da0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 ines.)^.** This
12db0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
12dc0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
12dd0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
12de0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
12df0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
12e00 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 rapper used to t
12e10 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 rack mutex usage
12e20 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
12e30 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 .** profiling or
12e40 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 testing, for ex
12e50 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c ample. ^If SQL
12e60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
12e70 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
12e80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
12e90 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
12ea0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
12eb0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
12ec0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
12ed0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
12ee0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
12ef0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
12f00 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
12f10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12f20 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
12f30 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
12f40 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
12f50 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
12f60 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12f70 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
12f80 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12f90 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 G_LOOKASIDE]] <d
12fa0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12fb0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
12fc0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 * <dd> ^(This op
12fd0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
12fe0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
12ff0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 termine the defa
13000 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c ult.** memory al
13010 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 location for the
13020 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
13030 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 y allocator on e
13040 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ach.** [database
13050 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
13060 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
13070 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
13080 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
13090 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 de buffer slot a
130a0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 nd the second is
130b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
130c0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 * slots allocate
130d0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 d to each databa
130e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e se connection.)^
130f0 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 ^(This option
13100 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 sets the.** <i>d
13110 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 efault</i> looka
13120 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b side size. The [
13130 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
13140 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 LOOKASIDE].** ve
13150 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 rb to [sqlite3_d
13160 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 b_config()] can
13170 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 be used to chang
13180 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a e the lookaside.
13190 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
131a0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 on individual c
131b0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f onnections.)^ </
131c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
131d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
131e0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
131f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 ONFIG_PCACHE2</d
13200 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
13210 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 s option takes a
13220 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
13230 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e which is a poin
13240 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 ter to.** an [sq
13250 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
13260 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 hods2] object.
13270 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
13280 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66 ifies the interf
13290 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 ace.** to a cust
132a0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
132b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 plementation.)^
132c0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
132d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
132e0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20 object and uses
132f0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 it for page cach
13300 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
13310 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ions.</dd>.**.**
13320 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13330 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 _GETPCACHE2]] <d
13340 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13350 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a GETPCACHE2</dt>.
13360 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
13370 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
13380 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
13390 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
133a0 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 to an.** [sqlit
133b0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
133c0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c s2] object. SQL
133d0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 ite copies of th
133e0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 e current.** pag
133f0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
13400 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 tation into that
13410 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e object.)^ </dd>
13420 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
13430 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 CONFIG_LOG]] <dt
13440 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c >SQLITE_CONFIG_L
13450 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OG</dt>.** <dd>
13460 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
13470 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 IG_LOG option ta
13480 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
13490 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 s: a pointer to
134a0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 a.** function wi
134b0 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 th a call signat
134c0 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 ure of void(*)(v
134d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 oid*,int,const c
134e0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 har*), .** and a
134f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 pointer to void
13500 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 . ^If the functi
13510 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
13520 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a t NULL, it is.**
13530 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c invoked by [sql
13540 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 ite3_log()] to p
13550 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 rocess each logg
13560 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
13570 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 the.** function
13580 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c pointer is NULL,
13590 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f the [sqlite3_lo
135a0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 g()] interface b
135b0 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a ecomes a no-op..
135c0 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 ** ^The void poi
135d0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 nter that is the
135e0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
135f0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 to SQLITE_CONFI
13600 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 G_LOG is.** pass
13610 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 ed through as th
13620 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
13630 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 r to the applica
13640 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
13650 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
13660 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 whenever that fu
13670 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 nction is invoke
13680 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 d. ^The second
13690 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
136a0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 the logger funct
136b0 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ion is a copy of
136c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
136d0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 eter to the corr
136e0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 esponding.** [sq
136f0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c lite3_log()] cal
13700 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 l and is intende
13710 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c d to be a [resul
13720 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a t code] or an.**
13730 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
13740 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 t code]. ^The t
13750 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 hird parameter p
13760 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 assed to the log
13770 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 ger is.** log me
13780 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d ssage after form
13790 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 atting via [sqli
137a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e te3_snprintf()].
137b0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c .** The SQLite l
137c0 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 ogging interface
137d0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
137e0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 t; the logger fu
137f0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 nction.** suppli
13800 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
13810 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 ation must not i
13820 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 nvoke any SQLite
13830 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 interface..** I
13840 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 n a multi-thread
13850 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 ed application,
13860 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
13870 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
13880 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
13890 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c be threadsafe. <
138a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
138b0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d ITE_CONFIG_URI]]
138c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
138d0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 IG_URI.** <dd> T
138e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
138f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
13900 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 nt of type int.
13910 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 If non-zero, the
13920 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e n.** URI handlin
13930 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
13940 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 abled. If the pa
13950 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c rameter is zero,
13960 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
13970 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c ng.** is globall
13980 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 y disabled. If U
13990 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
139a0 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c lobally enabled,
139b0 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a all filenames.*
139c0 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c * passed to [sql
139d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
139e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
139f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
13a00 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 16()] or.** spec
13a10 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 ified as part of
13a20 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e [ATTACH] comman
13a30 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 ds are interpret
13a40 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 ed as URIs, rega
13a50 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 rdless.** of whe
13a60 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
13a70 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
13a80 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 ] flag is set wh
13a90 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a en the database.
13aa0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
13ab0 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 opened. If it i
13ac0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
13ad0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 led, filenames a
13ae0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 re.** only inter
13af0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 preted as URIs i
13b00 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 f the SQLITE_OPE
13b10 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 N_URI flag is se
13b20 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 t when the.** da
13b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
13b40 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 n is opened. By
13b50 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e default, URI han
13b60 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
13b70 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 y.** disabled. T
13b80 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
13b90 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 may be changed
13ba0 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 by compiling wit
13bb0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
13bc0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c _USE_URI] symbol
13bd0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
13be0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13bf0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
13c00 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 CAN]] <dt>SQLITE
13c10 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
13c20 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c _INDEX_SCAN.** <
13c30 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 dd> This option
13c40 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 takes a single i
13c50 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20 nteger argument
13c60 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 which is interpr
13c70 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f eted as.** a boo
13c80 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f lean in order to
13c90 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
13ca0 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f le the use of co
13cb0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
13cc0 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 or.** full table
13cd0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 scans in the qu
13ce0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 ery optimizer.
13cf0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
13d00 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 ing is determine
13d10 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c d.** by the [SQL
13d20 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 ITE_ALLOW_COVERI
13d30 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 NG_INDEX_SCAN] c
13d40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
13d50 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a on, or is "on".*
13d60 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c * if that compil
13d70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
13d80 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 omitted..** The
13d90 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 ability to disa
13da0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 ble the use of c
13db0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
13dc0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
13dd0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 cans.** is becau
13de0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 se some incorrec
13df0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 tly coded legacy
13e00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 applications mi
13e10 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a ght malfunction.
13e20 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77 ** malfunction w
13e30 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 hen the optimiza
13e40 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e tion is enabled.
13e50 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 Providing the
13e60 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 ability to.** di
13e70 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 sable the optimi
13e80 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 zation allows th
13e90 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 e older, buggy a
13ea0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
13eb0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f to work.** witho
13ec0 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 ut change even w
13ed0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f ith newer versio
13ee0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a ns of SQLite..**
13ef0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
13f00 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 FIG_PCACHE]] [[S
13f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
13f20 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e PCACHE]].** <dt>
13f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
13f40 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f ACHE and SQLITE_
13f50 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
13f60 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f .** <dd> These o
13f70 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c ptions are obsol
13f80 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e ete and should n
13f90 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 ot be used by ne
13fa0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 w code..** They
13fb0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 are retained for
13fc0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
13fd0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 tibility but are
13fe0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 now no-ops..**
13ff0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dl>.**.** [[SQ
14000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
14010 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 OG]].** <dt>SQLI
14020 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
14030 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
14040 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
14050 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 lable if sqlite
14060 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
14070 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45 the.** SQLITE_E
14080 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65 NABLE_SQLLOG pre
14090 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
140a0 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 defined. The fi
140b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rst argument sho
140c0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e uld.** be a poin
140d0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f ter to a functio
140e0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a n of type void(*
140f0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
14100 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e ,const char*, in
14110 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e t)..** The secon
14120 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 d should be of t
14130 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 ype (void*). The
14140 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
14150 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 oked by the libr
14160 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 ary.** in three
14170 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 separate circums
14180 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 tances, identifi
14190 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 ed by the value
141a0 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a passed as the.**
141b0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
141c0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 r. If the fourth
141d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c parameter is 0,
141e0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
141f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
14200 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
14210 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 econd argument h
14220 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 as just been ope
14230 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 ned. The third a
14240 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 rgument.** point
14250 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f s to a buffer co
14260 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d ntaining the nam
14270 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 e of the main da
14280 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 tabase file. If
14290 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
142a0 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 rameter is 1, th
142b0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
142c0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 ment that the th
142d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ird parameter.**
142e0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a points to has j
142f0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 ust been execute
14300 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f d. Or, if the fo
14310 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
14320 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 s 2, then.** the
14330 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e connection bein
14340 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 g passed as the
14350 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
14360 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 is being closed
14370 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 . The.** third p
14380 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 arameter is pass
14390 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 ed NULL In this
143a0 63 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 case..**.** [[SQ
143b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
143c0 5f 4c 49 4d 49 54 5d 5d 0a 2a 2a 20 3c 64 74 3e _LIMIT]].** <dt>
143d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
143e0 41 50 5f 4c 49 4d 49 54 0a 2a 2a 20 3c 64 64 3e AP_LIMIT.** <dd>
143f0 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e The sole argumen
14400 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 36 34 t should be a 64
14410 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 61 6e -bit integer (an
14420 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 sqlite3_int64)
14430 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 64 that.** is the d
14440 65 66 61 75 6c 74 20 6d 61 78 69 6d 75 6d 20 6e efault maximum n
14450 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
14460 66 20 70 72 6f 63 65 73 73 20 61 64 64 72 65 73 f process addres
14470 73 20 73 70 61 63 65 20 74 68 61 74 0a 2a 2a 20 s space that.**
14480 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20 66 should be used f
14490 6f 72 20 61 63 63 65 73 73 69 6e 67 20 65 61 63 or accessing eac
144a0 68 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 h database file
144b0 75 73 69 6e 67 20 6d 65 6d 6f 72 79 20 6d 61 70 using memory map
144c0 70 69 6e 67 2e 0a 2a 2a 20 54 68 65 20 64 65 66 ping..** The def
144d0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e ault setting can
144e0 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 be overridden b
144f0 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 y each database
14500 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 connection using
14510 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b .** either the [
14520 50 52 41 47 4d 41 20 6d 6d 61 70 5f 6c 69 6d 69 PRAGMA mmap_limi
14530 74 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 t] command, or b
14540 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b y using the.** [
14550 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
14560 50 5f 4c 49 4d 49 54 5d 20 66 69 6c 65 20 63 6f P_LIMIT] file co
14570 6e 74 72 6f 6c 2e 20 20 54 68 65 20 76 61 6c 75 ntrol. The valu
14580 65 20 73 65 74 20 68 65 72 65 20 6f 76 65 72 72 e set here overr
14590 69 64 65 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 ides the.** comp
145a0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 ile-time default
145b0 20 74 68 61 74 20 69 73 20 73 65 74 20 75 73 69 that is set usi
145c0 6e 67 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 ng [SQLITE_DEFAU
145d0 4c 54 5f 4d 4d 41 50 5f 4c 49 4d 49 54 5d 2e 0a LT_MMAP_LIMIT]..
145e0 2a 2a 20 49 66 20 74 68 65 20 61 72 67 75 6d 65 ** If the argume
145f0 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f nt to this optio
14600 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 n is negative, t
14610 68 65 6e 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 hen.** the memor
14620 79 20 6d 61 70 20 6c 69 6d 69 74 20 69 73 20 73 y map limit is s
14630 65 74 20 74 6f 20 74 68 65 20 63 6f 6d 70 69 6c et to the compil
14640 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a e-time default..
14650 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
14660 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14670 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 G_SINGLETHREAD
14680 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 1 /* nil */.#de
14690 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
146a0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 IG_MULTITHREAD
146b0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 2 /* nil */.#d
146c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
146d0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 FIG_SERIALIZED
146e0 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 3 /* nil */.#
146f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
14700 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 NFIG_MALLOC
14710 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 4 /* sqlite3
14720 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
14730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
14740 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
14750 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 5 /* sqlit
14760 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 e3_mem_methods*
14770 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14780 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
14790 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 6 /* voi
147a0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
147b0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
147c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
147d0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 ACHE 7 /* v
147e0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e oid*, int sz, in
147f0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t N */.#define S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
14810 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a P 8 /*
14820 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 void*, int nByt
14830 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 e, int min */.#d
14840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
14850 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 FIG_MEMSTATUS
14860 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 9 /* boolean
14870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14880 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 E_CONFIG_MUTEX
14890 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 10 /* sql
148a0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
148b0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
148c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
148d0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a MUTEX 11 /*
148e0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
148f0 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 ethods* */./* pr
14900 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f eviously SQLITE_
14910 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f CONFIG_CHUNKALLO
14920 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f C 12 which is no
14930 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 w unused. */ .#d
14940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
14950 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 FIG_LOOKASIDE
14960 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 13 /* int int
14970 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14980 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 E_CONFIG_PCACHE
14990 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 14 /* no-
149a0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
149b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
149c0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 CACHE 15 /*
149d0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 no-op */.#define
149e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
149f0 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 OG 16
14a00 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 /* xFunc, void*
14a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14a20 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 E_CONFIG_URI
14a30 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 17 /* int
14a40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14a50 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
14a60 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 2 18 /* sq
14a70 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
14a80 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e hods2* */.#defin
14a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14aa0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 GETPCACHE2 19
14ab0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
14ac0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
14ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
14ae0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
14af0 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a NDEX_SCAN 20 /*
14b00 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
14b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
14b20 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f LLOG 21 /
14b30 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a * xSqllog, void*
14b40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 4c TE_CONFIG_MMAP_L
14b60 49 4d 49 54 20 20 20 32 32 20 20 2f 2a 20 73 71 IMIT 22 /* sq
14b70 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 0a lite3_int64 */..
14b80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
14b90 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
14ba0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
14bb0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
14bc0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
14bd0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
14be0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
14bf0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
14c00 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
14c10 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
14c20 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
14c30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
14c40 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
14c50 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
14c60 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
14c70 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
14c80 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
14c90 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
14ca0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
14cb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
14cc0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
14cd0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
14ce0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
14cf0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
14d00 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
14d10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
14d20 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
14d30 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
14d40 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
14d50 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
14d60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
14d70 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
14d80 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
14d90 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
14da0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
14db0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
14dc0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
14dd0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
14de0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
14df0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
14e00 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
14e10 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
14e20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 takes three addi
14e30 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
14e40 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
14e50 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 the .** [lookasi
14e60 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 de memory alloca
14e70 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 tor] configurati
14e80 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 on for the [data
14e90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
14ea0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
14eb0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
14ec0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
14ed0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
14ee0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
14ef0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
14f00 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 ry buffer to use
14f10 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d for lookaside m
14f20 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 emory..** ^The f
14f30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 irst argument af
14f40 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ter the SQLITE_D
14f50 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
14f60 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 E verb.** may be
14f70 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 NULL in which c
14f80 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ase SQLite will
14f90 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 allocate the.**
14fa0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
14fb0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 itself using [s
14fc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
14fd0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . ^The second ar
14fe0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
14ff0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
15000 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
15010 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 lot. ^The third
15020 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
15030 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
15040 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f ots. The size o
15050 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 f the buffer in
15060 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
15070 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 nt must be great
15080 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 er than.** or eq
15090 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 ual to the produ
150a0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ct of the second
150b0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d and third argum
150c0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 ents. The buffe
150d0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 r.** must be ali
150e0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
150f0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 e boundary. ^If
15100 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
15110 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 ment to.** SQLIT
15120 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
15130 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 SIDE is not a mu
15140 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 ltiple of 8, it
15150 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a is internally.**
15160 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f rounded down to
15170 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 the next smalle
15180 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e r multiple of 8.
15190 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 ^(The lookasid
151a0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 e memory.** conf
151b0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 iguration for a
151c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
151d0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ion can only be
151e0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 changed when tha
151f0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 t.** connection
15200 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
15210 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 using lookaside
15220 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f memory, or in o
15230 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 ther words.** wh
15240 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 en the "current
15250 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 value" returned
15260 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 by.** [sqlite3_d
15270 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c b_status](D,[SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
15290 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 SIDE],...) is ze
152a0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ro..** Any attem
152b0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 pt to change the
152c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
152d0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 y configuration
152e0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a when lookaside.*
152f0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 * memory is in u
15300 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f se leaves the co
15310 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 nfiguration unch
15320 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
15330 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 s .** [SQLITE_BU
15340 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a SY].)^</dd>.**.*
15350 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
15360 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
15370 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e Y</dt>.** <dd> ^
15380 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
15390 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
153a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 disable the enf
153b0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b orcement of.** [
153c0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 foreign key cons
153d0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 traints]. There
153e0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
153f0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
15400 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
15410 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
15420 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
15430 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 s 0 to disable F
15440 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a K enforcement,.*
15450 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
15460 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
15470 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ent or negative
15480 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f to leave FK enfo
15490 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 rcement.** uncha
154a0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e nged. The secon
154b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
154c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
154d0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
154e0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
154f0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
15500 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e te whether FK en
15510 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 forcement is off
15520 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 or on.** follow
15530 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
15540 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
15550 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
15560 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
15570 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
15580 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
15590 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
155a0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
155b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
155c0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
155d0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 ABLE_TRIGGER</dt
155e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
155f0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
15600 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
15610 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 ble [CREATE TRIG
15620 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e GER | triggers].
15630 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
15640 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
15650 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
15660 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
15670 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
15680 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
15690 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 disable triggers
156a0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
156b0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 enable triggers
156c0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
156d0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
156e0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
156f0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
15700 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
15710 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
15720 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
15730 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
15740 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
15750 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 her triggers are
15760 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
15770 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e bled.** followin
15780 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
15790 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
157a0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
157b0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
157c0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 which case the t
157d0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 rigger setting i
157e0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
157f0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
15800 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
15810 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
15820 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 G_LOOKASIDE
15830 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 1001 /* void*
15840 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 int int */.#def
15850 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
15860 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 FIG_ENABLE_FKEY
15870 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 1002 /* int
15880 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
15890 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
158a0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 _ENABLE_TRIGGER
158b0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 1003 /* int in
158c0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t* */.../*.** CA
158d0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
158e0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
158f0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
15900 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
15910 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
15920 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
15930 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
15940 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
15950 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
15960 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
15970 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 SQLite. ^The ex
15980 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
15990 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 codes are disab
159a0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
159b0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
159c0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a mpatibility..*/.
159d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
159e0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
159f0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
15a00 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
15a10 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
15a20 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a sert Rowid.**.**
15a30 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 ^Each entry in
15a40 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 an SQLite table
15a50 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
15a60 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
15a70 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
15a80 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 the [ROWID | "r
15a90 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 owid"]. ^The row
15aa0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
15ab0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
15ac0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
15ad0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
15ae0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
15af0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
15b00 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
15b10 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
15b20 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
15b30 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a d columns. ^If.*
15b40 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
15b50 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
15b60 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
15b70 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
15b80 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
15b90 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
15ba0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
15bb0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 ^This routine r
15bc0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 eturns the [rowi
15bd0 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 d] of the most r
15be0 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 ecent.** success
15bf0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 ful [INSERT] int
15c00 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 o the database f
15c10 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 rom the [databas
15c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a e connection].**
15c30 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
15c40 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 gument. ^As of
15c50 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
15c60 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 .7.7, this routi
15c70 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 nes.** records t
15c80 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 he last insert r
15c90 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 owid of both ord
15ca0 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 inary tables and
15cb0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 [virtual tables
15cc0 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 ]..** ^If no suc
15cd0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
15ce0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
15cf0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 ccurred on that
15d00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
15d10 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 ion, zero is ret
15d20 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 urned..**.** ^(I
15d30 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 f an [INSERT] oc
15d40 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 curs within a tr
15d50 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 igger or within
15d60 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 a [virtual table
15d70 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 ].** method, the
15d80 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 n this routine w
15d90 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b ill return the [
15da0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e rowid] of the in
15db0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 serted.** row as
15dc0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 long as the tri
15dd0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 gger or virtual
15de0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 table method is
15df0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 running..** But
15e00 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 once the trigger
15e10 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c or virtual tabl
15e20 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 e method ends, t
15e30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
15e40 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f d .** by this ro
15e50 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f utine reverts to
15e60 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 what it was bef
15e70 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ore the trigger
15e80 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 or virtual.** ta
15e90 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e ble method began
15ea0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 .)^.**.** ^An [I
15eb0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c NSERT] that fail
15ec0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 s due to a const
15ed0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 raint violation
15ee0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 is not a.** succ
15ef0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
15f00 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 and does not cha
15f10 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 nge the value re
15f20 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a turned by this.*
15f30 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 * routine. ^Thu
15f40 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c s INSERT OR FAIL
15f50 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f , INSERT OR IGNO
15f60 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f RE, INSERT OR RO
15f70 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 LLBACK,.** and I
15f80 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d NSERT OR ABORT m
15f90 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 ake no changes t
15fa0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c o the return val
15fb0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f ue of this.** ro
15fc0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 utine when their
15fd0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 insertion fails
15fe0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 . ^(When INSERT
15ff0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 OR REPLACE.** e
16000 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 ncounters a cons
16010 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
16020 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 , it does not fa
16030 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 il. The.** INSE
16040 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 RT continues to
16050 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 completion after
16060 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 deleting rows t
16070 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 hat caused.** th
16080 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f e constraint pro
16090 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f blem so INSERT O
160a0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 R REPLACE will a
160b0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 lways change.**
160c0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
160d0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 of this interfa
160e0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 ce.)^.**.** ^For
160f0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 the purposes of
16100 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 this routine, a
16110 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f n [INSERT] is co
16120 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 nsidered to.** b
16130 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 e successful eve
16140 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 n if it is subse
16150 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 quently rolled b
16160 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ack..**.** This
16170 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 function is acce
16180 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 ssible to SQL st
16190 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 atements via the
161a0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 .** [last_insert
161b0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e _rowid() SQL fun
161c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
161d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
161e0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 ad performs a ne
161f0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 w [INSERT] on th
16200 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 e same.** databa
16210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 se connection wh
16220 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ile the [sqlite3
16230 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
16240 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f id()].** functio
16250 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 n is running and
16260 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 thus changes th
16270 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 e last insert [r
16280 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 owid],.** then t
16290 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
162a0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 d by [sqlite3_la
162b0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
162c0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 )] is.** unpredi
162d0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 ctable and might
162e0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 not equal eithe
162f0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 r the old or the
16300 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 new.** last ins
16310 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a ert [rowid]..*/.
16320 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
16330 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
16340 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
16350 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
16360 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 EF: Count The Nu
16370 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 mber Of Rows Mod
16380 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 ified.**.** ^Thi
16390 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
163a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
163b0 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 database rows t
163c0 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 hat were changed
163d0 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 .** or inserted
163e0 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 or deleted by th
163f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 e most recently
16400 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 completed SQL st
16410 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 atement.** on th
16420 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
16430 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
16440 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 d by the first p
16450 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f arameter..** ^(O
16460 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 nly changes that
16470 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 are directly sp
16480 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b ecified by the [
16490 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 INSERT], [UPDATE
164a0 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 ],.** or [DELETE
164b0 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 ] statement are
164c0 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 counted. Auxili
164d0 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 ary changes caus
164e0 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 ed by.** trigger
164f0 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 s or [foreign ke
16500 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e y actions] are n
16510 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 ot counted.)^ Us
16520 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 e the.** [sqlite
16530 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
16540 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 )] function to f
16550 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 ind the total nu
16560 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a mber of changes.
16570 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 ** including cha
16580 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 nges caused by t
16590 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 riggers and fore
165a0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e ign key actions.
165b0 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 .**.** ^Changes
165c0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 to a view that a
165d0 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 re simulated by
165e0 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 an [INSTEAD OF t
165f0 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e rigger].** are n
16600 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c ot counted. Onl
16610 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 y real table cha
16620 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 nges are counted
16630 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 ..**.** ^(A "row
16640 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 change" is a ch
16650 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 ange to a single
16660 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 row of a single
16670 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 table.** caused
16680 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 by an INSERT, D
16690 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 ELETE, or UPDATE
166a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 statement. Row
166b0 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 s that.** are ch
166c0 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 anged as side ef
166d0 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 fects of [REPLAC
166e0 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 E] constraint re
166f0 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c solution,.** rol
16700 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f lback, ABORT pro
16710 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 cessing, [DROP T
16720 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 ABLE], or by any
16730 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e other.** mechan
16740 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e isms do not coun
16750 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 t as direct row
16760 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a changes.)^.**.**
16770 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 A "trigger cont
16780 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 ext" is a scope
16790 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 of execution tha
167a0 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 t begins and.**
167b0 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 ends with the sc
167c0 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 ript of a [CREAT
167d0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
167e0 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 ger]. .** Most S
167f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
16800 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f e.** evaluated o
16810 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 utside of any tr
16820 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 igger. This is
16830 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a the "top level".
16840 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ** trigger conte
16850 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 xt. If a trigge
16860 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 r fires from the
16870 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a top level, a.**
16880 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e new trigger con
16890 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 text is entered
168a0 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e for the duration
168b0 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 of that one.**
168c0 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 trigger. Subtri
168d0 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 ggers create sub
168e0 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 contexts for the
168f0 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a ir duration..**.
16900 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c ** ^Calling [sql
16910 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 ite3_exec()] or
16920 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
16930 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 recursively doe
16940 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 s.** not create
16950 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f a new trigger co
16960 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ntext..**.** ^Th
16970 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
16980 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
16990 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 f direct row cha
169a0 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d nges in the.** m
169b0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 ost recent INSER
169c0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
169d0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 LETE statement w
169e0 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a ithin the same.*
169f0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 * trigger contex
16a00 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 t..**.** ^Thus,
16a10 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d when called from
16a20 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 the top level,
16a30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 this function re
16a40 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d turns the.** num
16a50 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 ber of changes i
16a60 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
16a70 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
16a80 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 , or DELETE.** t
16a90 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 hat also occurre
16aa0 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 d at the top lev
16ab0 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 el. ^(Within th
16ac0 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 e body of a trig
16ad0 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 ger,.** the sqli
16ae0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e te3_changes() in
16af0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 terface can be c
16b00 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 alled to find th
16b10 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
16b20 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
16b30 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
16b40 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
16b50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
16b60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 ** statement wit
16b70 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 hin the body of
16b80 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 the same trigger
16b90 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 ..** However, th
16ba0 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 e number returne
16bb0 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 d does not inclu
16bc0 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 de changes.** ca
16bd0 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 used by subtrigg
16be0 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 ers since those
16bf0 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 have their own c
16c00 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ontext.)^.**.**
16c10 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
16c20 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
16c30 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
16c40 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f , the.** [count_
16c50 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c changes pragma],
16c60 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 and the [change
16c70 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
16c80 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 ]..**.** If a se
16c90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 parate thread ma
16ca0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 kes changes on t
16cb0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
16cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 connection.** w
16cd0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 hile [sqlite3_ch
16ce0 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e anges()] is runn
16cf0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c ing then the val
16d00 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 ue returned.** i
16d10 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 s unpredictable
16d20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 and not meaningf
16d30 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 ul..*/.int sqlit
16d40 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 e3_changes(sqlit
16d50 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
16d60 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d I3REF: Total Num
16d70 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 ber Of Rows Modi
16d80 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 fied.**.** ^This
16d90 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
16da0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
16db0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 row changes caus
16dc0 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a ed by [INSERT],.
16dd0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b ** [UPDATE] or [
16de0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
16df0 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 ts since the [da
16e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16e10 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a n] was opened..*
16e20 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 * ^(The count re
16e30 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
16e40 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
16e50 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 ) includes all c
16e60 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 hanges.** from a
16e70 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 ll [CREATE TRIGG
16e80 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f ER | trigger] co
16e90 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 ntexts and chang
16ea0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 es made by.** [f
16eb0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
16ec0 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ns]. However,.**
16ed0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 the count does
16ee0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e not include chan
16ef0 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c ges used to impl
16f00 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 ement [REPLACE]
16f10 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 constraints,.**
16f20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 do rollbacks or
16f30 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
16f40 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 , or [DROP TABLE
16f50 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 ] processing. T
16f60 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 he.** count does
16f70 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 not include row
16f80 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 s of views that
16f90 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 fire an [INSTEAD
16fa0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a OF trigger],.**
16fb0 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 though if the I
16fc0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
16fd0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 r makes changes
16fe0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 of its own, thos
16ff0 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 e changes .** ar
17000 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 e counted.)^.**
17010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 ^The sqlite3_tot
17020 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e al_changes() fun
17030 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 ction counts the
17040 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e changes as soon
17050 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 as.** the state
17060 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 ment that makes
17070 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 them is complete
17080 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 d (when the stat
17090 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 ement handle.**
170a0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 is passed to [sq
170b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
170c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
170d0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 ize()])..**.** S
170e0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
170f0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
17100 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a interface, the.*
17110 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 * [count_changes
17120 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 pragma], and th
17130 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e [total_changes
17140 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
17150 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
17160 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b arate thread mak
17170 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 es changes on th
17180 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
17190 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 connection.** wh
171a0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 ile [sqlite3_tot
171b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 al_changes()] is
171c0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
171d0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
171e0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 ned is unpredict
171f0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
17200 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 ningful..*/.int
17210 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
17220 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b anges(sqlite3*);
17230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
17240 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f : Interrupt A Lo
17250 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 ng-Running Query
17260 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e .**.** ^This fun
17270 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 ction causes any
17280 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 pending databas
17290 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 e operation to a
172a0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 bort and.** retu
172b0 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 rn at its earlie
172c0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 st opportunity.
172d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 This routine is
172e0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c typically.** cal
172f0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 led in response
17300 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e to a user action
17310 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e such as pressin
17320 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 g "Cancel".** or
17330 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 Ctrl-C where th
17340 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c e user wants a l
17350 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 ong query operat
17360 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 ion to halt.** i
17370 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a mmediately..**.*
17380 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f * ^It is safe to
17390 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
173a0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 ne from a thread
173b0 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 different from
173c0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 the.** thread th
173d0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 at is currently
173e0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 running the data
173f0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 base operation.
17400 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f But it.** is no
17410 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 t safe to call t
17420 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 his routine with
17430 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
17440 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a nection] that.**
17450 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 is closed or mi
17460 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 ght close before
17470 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
17480 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a pt() returns..**
17490 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f .** ^If an SQL o
174a0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 peration is very
174b0 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 nearly finished
174c0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 at the time whe
174d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 n.** sqlite3_int
174e0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c errupt() is call
174f0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 ed, then it migh
17500 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 t not have an op
17510 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 portunity.** to
17520 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 be interrupted a
17530 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 nd might continu
17540 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e e to completion.
17550 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f .**.** ^An SQL o
17560 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 peration that is
17570 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c interrupted wil
17580 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
17590 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 _INTERRUPT]..**
175a0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 ^If the interrup
175b0 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f ted SQL operatio
175c0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 n is an INSERT,
175d0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 UPDATE, or DELET
175e0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 E.** that is ins
175f0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 ide an explicit
17600 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 transaction, the
17610 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 n the entire tra
17620 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c nsaction.** will
17630 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
17640 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a automatically..*
17650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
17660 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 3_interrupt(D) c
17670 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 all is in effect
17680 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 until all curre
17690 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 ntly running.**
176a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f SQL statements o
176b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
176c0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 ection] D comple
176d0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 te. ^Any new SQ
176e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
176f0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
17700 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
17710 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
17720 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 all and before t
17730 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 he .** running s
17740 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 tatements reache
17750 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 s zero are inter
17760 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 rupted as if the
17770 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 y had been.** ru
17780 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 nning prior to t
17790 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
177a0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e rupt() call. ^N
177b0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ew SQL statement
177c0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
177d0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
177e0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e running statemen
177f0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 t count reaches
17800 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 zero are.** not
17810 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 effected by the
17820 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
17830 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 t()..** ^A call
17840 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 to sqlite3_inter
17850 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 rupt(D) that occ
17860 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 urs when there a
17870 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a re no running.**
17880 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
17890 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 is a no-op and h
178a0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 as no effect on
178b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
178c0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
178d0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
178e0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
178f0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a call returns..*
17900 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 *.** If the data
17910 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
17920 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 closes while [sq
17930 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
17940 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 )].** is running
17950 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 then bad things
17960 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 will likely hap
17970 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c pen..*/.void sql
17980 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 ite3_interrupt(s
17990 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
179a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
179b0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 mine If An SQL S
179c0 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 tatement Is Comp
179d0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 lete.**.** These
179e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
179f0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d eful during comm
17a00 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 and-line input t
17a10 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 o determine if t
17a20 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 he.** currently
17a30 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 entered text see
17a40 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d ms to form a com
17a50 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
17a60 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 ent or.** if add
17a70 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 itional input is
17a80 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 needed before s
17a90 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 ending the text
17aa0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 into.** SQLite f
17ab0 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 or parsing. ^Th
17ac0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
17ad0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 urn 1 if the inp
17ae0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 ut string.** app
17af0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d ears to be a com
17b00 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
17b10 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 ent. ^A stateme
17b20 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 nt is judged to
17b30 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 be.** complete i
17b40 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 f it ends with a
17b50 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e semicolon token
17b60 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 and is not a pr
17b70 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c efix of a.** wel
17b80 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 l-formed CREATE
17b90 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e TRIGGER statemen
17ba0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 t. ^Semicolons
17bb0 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 that are embedde
17bc0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 d within.** stri
17bd0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 ng literals or q
17be0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 uoted identifier
17bf0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e names or commen
17c00 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e ts are not.** in
17c10 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 dependent tokens
17c20 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 (they are part
17c30 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 of the token in
17c40 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a which they are.*
17c50 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 * embedded) and
17c60 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e thus do not coun
17c70 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 t as a statement
17c80 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 terminator. ^W
17c90 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 hitespace.** and
17ca0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 comments that f
17cb0 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 ollow the final
17cc0 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 semicolon are ig
17cd0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 nored..**.** ^Th
17ce0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
17cf0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 urn 0 if the sta
17d00 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 tement is incomp
17d10 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 lete. ^If a.**
17d20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
17d30 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 n fails, then SQ
17d40 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 LITE_NOMEM is re
17d50 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
17d60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f hese routines do
17d70 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 not parse the S
17d80 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 QL statements th
17d90 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 us.** will not d
17da0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 etect syntactica
17db0 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 lly incorrect SQ
17dc0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 L..**.** ^(If SQ
17dd0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 Lite has not bee
17de0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 n initialized us
17df0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ing [sqlite3_ini
17e00 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 tialize()] prior
17e10 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 .** to invoking
17e20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
17e30 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 e16() then sqlit
17e40 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
17e50 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 is invoked.** au
17e60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 tomatically by s
17e70 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
17e80 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 6(). If that in
17e90 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 itialization fai
17ea0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ls,.** then the
17eb0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
17ec0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 m sqlite3_comple
17ed0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e te16() will be n
17ee0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 on-zero.** regar
17ef0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
17f00 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 or not the inpu
17f10 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 t SQL is complet
17f20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 e.)^.**.** The i
17f30 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
17f40 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 _complete()] mus
17f50 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
17f60 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 inated.** UTF-8
17f70 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 string..**.** Th
17f80 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
17f90 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
17fa0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
17fb0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
17fc0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 TF-16 string in
17fd0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
17fe0 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 r..*/.int sqlite
17ff0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 3_complete(const
18000 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 char *sql);.int
18010 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
18020 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a e16(const void *
18030 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 sql);../*.** CAP
18040 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
18050 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 A Callback To Ha
18060 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 ndle SQLITE_BUSY
18070 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 Errors.**.** ^T
18080 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 his routine sets
18090 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
180a0 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 tion that might
180b0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
180c0 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 ver.** an attemp
180d0 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 t is made to ope
180e0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 n a database tab
180f0 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 le that another
18100 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f thread.** or pro
18110 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e cess has locked.
18120 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 .**.** ^If the b
18130 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 usy callback is
18140 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 NULL, then [SQLI
18150 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c TE_BUSY] or [SQL
18160 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 ITE_IOERR_BLOCKE
18170 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 D].** is returne
18180 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 d immediately up
18190 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 on encountering
181a0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 the lock. ^If t
181b0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
181c0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c .** is not NULL,
181d0 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 then the callba
181e0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f ck might be invo
181f0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
18200 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 uments..**.** ^T
18210 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
18220 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 t to the busy ha
18230 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 ndler is a copy
18240 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 of the void* poi
18250 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 nter which.** is
18260 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
18270 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
18280 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 usy_handler().
18290 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
182a0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 ment to.** the b
182b0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c usy handler call
182c0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 back is the numb
182d0 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
182e0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
182f0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e r has.** been in
18300 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c voked for this l
18310 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e ocking event. ^
18320 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 If the.** busy c
18330 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
18340 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 0, then no addit
18350 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 ional attempts a
18360 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 re made to.** ac
18370 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
18380 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 e and [SQLITE_BU
18390 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 SY] or [SQLITE_I
183a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 OERR_BLOCKED] is
183b0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 returned..** ^I
183c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
183d0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
183e0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 then another at
183f0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 tempt.** is made
18400 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 to open the dat
18410 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e abase for readin
18420 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 g and the cycle
18430 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 repeats..**.** T
18440 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 he presence of a
18450 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f busy handler do
18460 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 es not guarantee
18470 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 that it will be
18480 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e invoked.** when
18490 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 there is lock c
184a0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 ontention. ^If S
184b0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 QLite determines
184c0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 that invoking t
184d0 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c he busy.** handl
184e0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 er could result
184f0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 in a deadlock, i
18500 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 t will go ahead
18510 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
18520 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b TE_BUSY].** or [
18530 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
18540 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 CKED] instead of
18550 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
18560 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
18570 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
18580 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
18590 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
185a0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
185b0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
185c0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
185d0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
185e0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
185f0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
18600 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
18610 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
18620 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
18630 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
18640 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
18650 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
18660 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
18670 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
18680 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
18690 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
186a0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
186b0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
186c0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
186d0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
186e0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
186f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
18700 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
18710 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
18720 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
18730 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
18740 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
18750 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
18760 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
18770 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
18780 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
18790 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
187a0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
187b0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
187c0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
187d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
187e0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 roceed..**.** ^T
187f0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
18800 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
18810 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ..**.** ^The [SQ
18820 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 LITE_BUSY] error
18830 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f is converted to
18840 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
18850 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 LOCKED].** when
18860 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 SQLite is in the
18870 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 middle of a lar
18880 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 ge transaction w
18890 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 here all the.**
188a0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 changes will not
188b0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e fit into the in
188c0 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 -memory cache.
188d0 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 SQLite will.** a
188e0 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 lready hold a RE
188f0 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 SERVED lock on t
18900 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
18910 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a , but it needs.*
18920 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 * to promote thi
18930 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 s lock to EXCLUS
18940 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 IVE so that it c
18950 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a an spill cache.*
18960 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 * pages into the
18970 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
18980 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 ithout harm to c
18990 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 oncurrent.** rea
189a0 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 ders. ^If it is
189b0 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f unable to promo
189c0 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 te the lock, the
189d0 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a n the in-memory.
189e0 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 ** cache will be
189f0 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f left in an inco
18a00 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 nsistent state a
18a10 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a nd so the error.
18a20 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f ** code is promo
18a30 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c ted from the rel
18a40 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b atively benign [
18a50 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a SQLITE_BUSY] to.
18a60 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 ** the more seve
18a70 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 re [SQLITE_IOERR
18a80 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 _BLOCKED]. ^Thi
18a90 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f s error code pro
18aa0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 motion.** forces
18ab0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f an automatic ro
18ac0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 llback of the ch
18ad0 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a anges. See the.
18ae0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 ** <a href="/cvs
18af0 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 trac/wiki?p=Corr
18b00 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
18b10 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f usyError">.** Co
18b20 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e rruptionFollowin
18b30 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 gBusyError</a> w
18b40 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 iki page for a d
18b50 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 iscussion of why
18b60 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f .** this is impo
18b70 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 rtant..**.** ^(T
18b80 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
18b90 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
18ba0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 andler defined f
18bb0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 or each.** [data
18bc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
18bd0 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 . Setting a new
18be0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c busy handler cl
18bf0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 ears any.** prev
18c00 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c iously set handl
18c10 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 er.)^ ^Note tha
18c20 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
18c30 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
18c40 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 )].** will also
18c50 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 set or clear the
18c60 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
18c70 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 *.** The busy ca
18c80 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f llback should no
18c90 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f t take any actio
18ca0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 ns which modify
18cb0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
18cc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
18cd0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
18ce0 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 handler. Any s
18cf0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 uch actions.** r
18d00 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e esult in undefin
18d10 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 ed behavior..**
18d20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c .** A busy handl
18d30 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 er must not clos
18d40 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
18d50 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 onnection.** or
18d60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
18d70 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 ent] that invoke
18d80 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
18d90 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 er..*/.int sqlit
18da0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
18db0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 sqlite3*, int(*)
18dc0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 (void*,int), voi
18dd0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
18de0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 3REF: Set A Busy
18df0 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e Timeout.**.** ^
18e00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 This routine set
18e10 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 s a [sqlite3_bus
18e20 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 y_handler | busy
18e30 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 handler] that s
18e40 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 leeps.** for a s
18e50 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 pecified amount
18e60 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 of time when a t
18e70 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 able is locked.
18e80 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a ^The handler.**
18e90 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 will sleep mult
18ea0 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c iple times until
18eb0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
18ec0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
18ed0 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 leeping.** have
18ee0 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 accumulated. ^A
18ef0 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d fter at least "m
18f00 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
18f10 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 of sleeping,.**
18f20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 the handler retu
18f30 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 rns 0 which caus
18f40 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 es [sqlite3_step
18f50 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a ()] to return.**
18f60 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f [SQLITE_BUSY] o
18f70 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f r [SQLITE_IOERR_
18f80 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 BLOCKED]..**.**
18f90 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f ^Calling this ro
18fa0 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 utine with an ar
18fb0 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e gument less than
18fc0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
18fd0 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 o.** turns off a
18fe0 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 ll busy handlers
18ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
19000 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
19010 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
19020 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c r for a particul
19030 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
19040 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 connection] any
19050 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 any given moment
19060 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 . If another bu
19070 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 sy handler.** wa
19080 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e s defined (usin
19090 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
190a0 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f handler()]) prio
190b0 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 r to calling.**
190c0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 this routine, th
190d0 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 at other busy ha
190e0 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 ndler is cleared
190f0 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 .)^.*/.int sqlit
19100 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
19110 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
19120 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
19130 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
19140 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
19150 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a ning Queries.**.
19160 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 ** This is a leg
19170 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 acy interface th
19180 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 at is preserved
19190 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f for backwards co
191a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 mpatibility..**
191b0 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 Use of this inte
191c0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 rface is not rec
191d0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 ommended..**.**
191e0 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 Definition: A <b
191f0 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 >result table</b
19200 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 > is memory data
19210 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 structure creat
19220 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 ed by the.** [sq
19230 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
19240 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 )] interface. A
19250 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 result table re
19260 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d cords the.** com
19270 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 plete query resu
19280 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 lts from one or
19290 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a more queries..**
192a0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f .** The table co
192b0 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 nceptually has a
192c0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 number of rows
192d0 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 and columns. Bu
192e0 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 t.** these numbe
192f0 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 rs are not part
19300 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 of the result ta
19310 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 ble itself. The
19320 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 se.** numbers ar
19330 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 e obtained separ
19340 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 ately. Let N be
19350 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
19360 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 ows.** and M be
19370 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f the number of co
19380 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 lumns..**.** A r
19390 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 esult table is a
193a0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 n array of point
193b0 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d ers to zero-term
193c0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 inated UTF-8 str
193d0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 ings..** There a
193e0 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 re (N+1)*M eleme
193f0 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 nts in the array
19400 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 . The first M p
19410 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a ointers point.**
19420 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 to zero-termina
19430 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 ted strings that
19440 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 contain the na
19450 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d mes of the colum
19460 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 ns..** The remai
19470 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c ning entries all
19480 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 point to query
19490 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 results. NULL v
194a0 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 alues result.**
194b0 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 in NULL pointers
194c0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c . All other val
194d0 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 ues are in their
194e0 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d UTF-8 zero-term
194f0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
19500 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 representation
19510 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b as returned by [
19520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
19530 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 ext()]..**.** A
19540 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 result table mig
19550 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e ht consist of on
19560 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 e or more memory
19570 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a allocations..**
19580 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
19590 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 to pass a result
195a0 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 table directly
195b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 to [sqlite3_free
195c0 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ()]..** A result
195d0 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 table should be
195e0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 deallocated usi
195f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ng [sqlite3_free
19600 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a _table()]..**.**
19610 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 ^(As an example
19620 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 of the result t
19630 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 able format, sup
19640 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 pose a query res
19650 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c ult.** is as fol
19660 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
19670 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
19680 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 Name
19690 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 | Age.**
196a0 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ------------
196b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 -----------.**
196c0 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 Alice
196d0 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 | 43.**
196e0 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 Bob | 2
196f0 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 8.** Cind
19700 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 y | 21.**
19710 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
19720 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 te>.**.** There
19730 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 are two column (
19740 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 M==2) and three
19750 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 rows (N==3). Th
19760 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 us the.** result
19770 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 table has 8 ent
19780 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 ries. Suppose t
19790 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
197a0 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 is stored.** in
197b0 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 an array names a
197c0 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 zResult. Then a
197d0 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 zResult holds th
197e0 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a is content:.**.*
197f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
19800 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a re>.** az
19810 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 Result[0] =
19820 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 "Name";.**
19830 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 azResult[1
19840 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 ] = "Age";.**
19850 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
19860 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 1;2] = "Alice";.
19870 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
19880 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 lt[3] = "43"
19890 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
198a0 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 sult[4] = "B
198b0 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ob";.** a
198c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d zResult[5] =
198d0 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "28";.**
198e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d azResult[6]
198f0 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 = "Cindy";.**
19900 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
19910 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 91;7] = "21";.**
19920 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
19930 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ote>)^.**.** ^Th
19940 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
19950 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 ble() function e
19960 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 valuates one or
19970 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f more.** semicolo
19980 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 n-separated SQL
19990 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 statements in th
199a0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
199b0 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e d UTF-8.** strin
199c0 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 g of its 2nd par
199d0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 ameter and retur
199e0 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ns a result tabl
199f0 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e e to the.** poin
19a00 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 ter given in its
19a10 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 3rd parameter..
19a20 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 **.** After the
19a30 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 application has
19a40 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 finished with th
19a50 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 e result from sq
19a60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
19a70 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 ),.** it must pa
19a80 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 ss the result ta
19a90 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 ble pointer to s
19aa0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
19ab0 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a e() in order to.
19ac0 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d ** release the m
19ad0 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d emory that was m
19ae0 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 alloced. Becaus
19af0 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 e of the way the
19b00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
19b10 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 loc()] happens w
19b20 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 ithin sqlite3_ge
19b30 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 t_table(), the c
19b40 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 alling.** functi
19b50 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 on must not try
19b60 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 to call [sqlite3
19b70 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c _free()] directl
19b80 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c y. Only.** [sql
19b90 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
19ba0 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 )] is able to re
19bb0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
19bc0 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 properly and sa
19bd0 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fely..**.** The
19be0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
19bf0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 e() interface is
19c00 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 implemented as
19c10 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 a wrapper around
19c20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 .** [sqlite3_exe
19c30 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 c()]. The sqlit
19c40 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 e3_get_table() r
19c50 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 outine does not
19c60 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 have access.** t
19c70 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 o any internal d
19c80 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f ata structures o
19c90 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 f SQLite. It us
19ca0 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c es only the publ
19cb0 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ic.** interface
19cc0 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 defined here. A
19cd0 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c s a consequence,
19ce0 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 errors that occ
19cf0 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 ur in the.** wra
19d00 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 pper layer outsi
19d10 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e de of the intern
19d20 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 al [sqlite3_exec
19d30 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 ()] call are not
19d40 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e .** reflected in
19d50 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
19d60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
19d70 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b rcode()] or.** [
19d80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 sqlite3_errmsg()
19d90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
19da0 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 3_get_table(. s
19db0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
19dc0 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 /* An open
19dd0 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f database */. co
19de0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
19df0 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
19e00 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 evaluated */.
19e10 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c char ***pazResul
19e20 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 t, /* Results
19e30 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f of the query */
19e40 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 . int *pnRow,
19e50 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 /* Numb
19e60 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 er of result row
19e70 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a s written here *
19e80 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d /. int *pnColum
19e90 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d n, /* Num
19ea0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f ber of result co
19eb0 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 lumns written he
19ec0 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 re */. char **p
19ed0 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a zErrmsg /*
19ee0 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 Error msg writt
19ef0 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f en here */.);.vo
19f00 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f id sqlite3_free_
19f10 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 table(char **res
19f20 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ult);../*.** CAP
19f30 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 I3REF: Formatted
19f40 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 String Printing
19f50 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
19f60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
19f70 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 are work-alikes
19f80 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 of the "printf()
19f90 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 " family of func
19fa0 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 tions.** from th
19fb0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
19fc0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rary..**.** ^The
19fd0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
19fe0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
19ff0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e mprintf() routin
1a000 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a es write their.*
1a010 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d * results into m
1a020 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
1a030 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
1a040 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 loc()]..** The s
1a050 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
1a060 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 by these two rou
1a070 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a tines should be.
1a080 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b ** released by [
1a090 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e sqlite3_free()].
1a0a0 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 ^Both routines
1a0b0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c return a.** NUL
1a0c0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 L pointer if [sq
1a0d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
1a0e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
1a0f0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 ocate enough.**
1a100 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 memory to hold t
1a110 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
1a120 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ing..**.** ^(The
1a130 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1a140 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 f() routine is s
1a150 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 imilar to "snpri
1a160 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 ntf()" from.** t
1a170 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
1a180 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 brary. The resu
1a190 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e lt is written in
1a1a0 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 to the.** buffer
1a1b0 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 supplied as the
1a1c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1a1d0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 r whose size is
1a1e0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 given by.** the
1a1f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
1a200 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f Note that the o
1a210 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 rder of the.** f
1a220 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 irst two paramet
1a230 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 ers is reversed
1a240 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e from snprintf().
1a250 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a )^ This is an.*
1a260 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 * historical acc
1a270 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f ident that canno
1a280 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f t be fixed witho
1a290 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 ut breaking.** b
1a2a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
1a2b0 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 bility. ^(Note
1a2c0 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 also that sqlite
1a2d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1a2e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
1a2f0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 r to its buffer
1a300 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e instead of the n
1a310 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 umber of.** char
1a320 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 acters actually
1a330 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
1a340 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 buffer.)^ We a
1a350 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 dmit that.** the
1a360 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 number of chara
1a370 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f cters written wo
1a380 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 uld be a more us
1a390 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 eful return.** v
1a3a0 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e alue but we cann
1a3b0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d ot change the im
1a3c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
1a3d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1a3e0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 ().** now withou
1a3f0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 t breaking compa
1a400 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
1a410 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 ^As long as the
1a420 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 buffer size is g
1a430 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f reater than zero
1a440 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e , sqlite3_snprin
1a450 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 tf().** guarante
1a460 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 es that the buff
1a470 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 er is always zer
1a480 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o-terminated. ^
1a490 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 The first.** par
1a4a0 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 ameter "n" is th
1a4b0 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 e total size of
1a4c0 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c the buffer, incl
1a4d0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a uding space for.
1a4e0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d ** the zero term
1a4f0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 inator. So the
1a500 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 longest string t
1a510 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c hat can be compl
1a520 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e etely.** written
1a530 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 will be n-1 cha
1a540 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e racters..**.** ^
1a550 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 The sqlite3_vsnp
1a560 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 rintf() routine
1a570 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 is a varargs ver
1a580 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f sion of sqlite3_
1a590 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a snprintf()..**.*
1a5a0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1a5b0 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 all implement s
1a5c0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 ome additional f
1a5d0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 ormatting.** opt
1a5e0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 ions that are us
1a5f0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 eful for constru
1a600 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d cting SQL statem
1a610 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 ents..** All of
1a620 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 the usual printf
1a630 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 () formatting op
1a640 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e tions apply. In
1a650 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 addition, there
1a660 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c .** is are "%q",
1a670 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 "%Q", and "%z"
1a680 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e options..**.** ^
1a690 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 (The %q option w
1a6a0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 orks like %s in
1a6b0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 that it substitu
1a6c0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e tes a nul-termin
1a6d0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 ated.** string f
1a6e0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 rom the argument
1a6f0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 list. But %q a
1a700 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 lso doubles ever
1a710 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 y '\'' character
1a720 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 ..** %q is desig
1a730 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 ned for use insi
1a740 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 de a string lite
1a750 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c ral.)^ By doubl
1a760 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a ing each '\''.**
1a770 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 character it es
1a780 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 capes that chara
1a790 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 cter and allows
1a7a0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 it to be inserte
1a7b0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 d into.** the st
1a7c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 ring..**.** For
1a7d0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 example, assume
1a7e0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 the string varia
1a7f0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 ble zText contai
1a800 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f ns text as follo
1a810 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
1a820 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1a830 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 char *zText = "I
1a840 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 t's a happy day!
1a850 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
1a860 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1a870 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 One can use this
1a880 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 text in an SQL
1a890 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c statement as fol
1a8a0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1a8b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1a8c0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 char *zSQL = s
1a8d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 qlite3_mprintf("
1a8e0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c INSERT INTO tabl
1a8f0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c e VALUES('%q')",
1a900 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
1a910 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
1a920 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
1a930 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
1a940 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
1a950 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1a960 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 ** Because the %
1a970 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 q format string
1a980 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 is used, the '\'
1a990 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a ' character in z
1a9a0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 Text.** is escap
1a9b0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 ed and the SQL g
1a9c0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 enerated is as f
1a9d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1a9e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1a9f0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 ** INSERT INTO
1aa00 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 table1 VALUES('I
1aa10 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 t''s a happy day
1aa20 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 !').** </pre></b
1aa30 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1aa40 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 This is correct
1aa50 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 . Had we used %
1aa60 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c s instead of %q,
1aa70 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 the generated S
1aa80 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 QL.** would have
1aa90 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 looked like thi
1aaa0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1aab0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
1aac0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
1aad0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 1 VALUES('It's a
1aae0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a happy day!');.*
1aaf0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1ab00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
1ab10 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 second example
1ab20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 is an SQL syntax
1ab30 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 error. As a ge
1ab40 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 neral rule you s
1ab50 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 hould.** always
1ab60 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f use %q instead o
1ab70 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 f %s when insert
1ab80 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 ing text into a
1ab90 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a string literal..
1aba0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f **.** ^(The %Q o
1abb0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
1abc0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c %q except it al
1abd0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 so adds single q
1abe0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 uotes around.**
1abf0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 the outside of t
1ac00 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e he total string.
1ac10 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 Additionally,
1ac20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
1ac30 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d in the.** argum
1ac40 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 ent list is a NU
1ac50 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 LL pointer, %Q s
1ac60 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 ubstitutes the t
1ac70 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 ext "NULL" (with
1ac80 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 out.** single qu
1ac90 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f otes).)^ So, fo
1aca0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 r example, one c
1acb0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 ould say:.**.**
1acc0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1acd0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1ace0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1acf0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1ad00 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 table VALUES(%Q)
1ad10 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
1ad20 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
1ad30 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
1ad40 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
1ad50 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
1ad60 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1ad70 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 *.** The code ab
1ad80 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 ove will render
1ad90 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 a correct SQL st
1ada0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a atement in the z
1adb0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 SQL.** variable
1adc0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 even if the zTex
1add0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 t variable is a
1ade0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
1adf0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 .** ^(The "%z" f
1ae00 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1ae10 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 works like "%s"
1ae20 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a but with the.**
1ae30 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 addition that a
1ae40 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 fter the string
1ae50 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e has been read an
1ae60 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a d copied into.**
1ae70 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 the result, [sq
1ae80 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 lite3_free()] is
1ae90 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 called on the i
1aea0 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a nput string.)^.*
1aeb0 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f /.char *sqlite3_
1aec0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
1aed0 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a ar*,...);.char *
1aee0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
1aef0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
1af00 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 _list);.char *sq
1af10 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 lite3_snprintf(i
1af20 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
1af30 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 har*, ...);.char
1af40 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 *sqlite3_vsnpri
1af50 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f ntf(int,char*,co
1af60 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 nst char*, va_li
1af70 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 st);../*.** CAPI
1af80 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
1af90 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 ocation Subsyste
1afa0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 m.**.** The SQLi
1afb0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 te core uses the
1afc0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 se three routine
1afd0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 s for all of its
1afe0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c own.** internal
1aff0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1b000 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 on needs. "Core"
1b010 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
1b020 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 sentence.** doe
1b030 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 s not include op
1b040 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 erating-system s
1b050 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c pecific VFS impl
1b060 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 ementation. The
1b070 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 .** Windows VFS
1b080 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c uses native mall
1b090 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1b0a0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 for some operati
1b0b0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ons..**.** ^The
1b0c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1b0d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1b0e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1b0f0 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f block.** of memo
1b100 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 ry at least N by
1b110 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 tes in length, w
1b120 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 here N is the pa
1b130 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 rameter..** ^If
1b140 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1b150 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 is unable to ob
1b160 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 tain sufficient
1b170 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 free.** memory,
1b180 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c it returns a NUL
1b190 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 L pointer. ^If
1b1a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 the parameter N
1b1b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 to.** sqlite3_ma
1b1c0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f lloc() is zero o
1b1d0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 r negative then
1b1e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1b1f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 returns.** a NU
1b200 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
1b210 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
1b220 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
1b230 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
1b240 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
1b250 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
1b260 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1b270 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
1b280 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
1b290 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
1b2a0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 t be reused. ^T
1b2b0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
1b2c0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
1b2d0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
1b2e0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
1b2f0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
1b300 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
1b310 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
1b320 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
1b330 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
1b340 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
1b350 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
1b360 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
1b370 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
1b380 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
1b390 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
1b3a0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
1b3b0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
1b3c0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
1b3d0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
1b3e0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
1b3f0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
1b400 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
1b410 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
1b420 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
1b430 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
1b440 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1b450 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
1b460 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
1b470 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
1b480 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1b490 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
1b4a0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 oc()..**.** ^(Th
1b4b0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f e sqlite3_reallo
1b4c0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 c() interface at
1b4d0 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 tempts to resize
1b4e0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f a.** prior memo
1b4f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
1b500 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 be at least N b
1b510 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 ytes, where N is
1b520 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 the.** second p
1b530 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d arameter. The m
1b540 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1b550 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 to be resized i
1b560 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 s the first.** p
1b570 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 arameter.)^ ^ If
1b580 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
1b590 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1b5a0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 realloc().** is
1b5b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1b5c0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 hen its behavior
1b5d0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f is identical to
1b5e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1b5f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 te3_malloc(N) wh
1b600 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
1b610 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ond parameter to
1b620 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1b630 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 ()..** ^If the s
1b640 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1b650 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1b660 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a oc() is zero or.
1b670 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e ** negative then
1b680 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
1b690 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d exactly the sam
1b6a0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 e as calling.**
1b6b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 sqlite3_free(P)
1b6c0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66 where P is the f
1b6d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1b6e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
1b6f0 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 c()..** ^sqlite3
1b700 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 _realloc() retur
1b710 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1b720 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
1b730 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 ion.** of at lea
1b740 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 st N bytes in si
1b750 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 ze or NULL if su
1b760 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
1b770 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a is unavailable..
1b780 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 ** ^If M is the
1b790 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f size of the prio
1b7a0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 r allocation, th
1b7b0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 en min(N,M) byte
1b7c0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f s.** of the prio
1b7d0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 r allocation are
1b7e0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 copied into the
1b7f0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 beginning of bu
1b800 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a ffer returned.**
1b810 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c by sqlite3_real
1b820 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 loc() and the pr
1b830 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 ior allocation i
1b840 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 s freed..** ^If
1b850 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1b860 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 ) returns NULL,
1b870 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 then the prior a
1b880 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 llocation.** is
1b890 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a not freed..**.**
1b8a0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 ^The memory ret
1b8b0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
1b8c0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 _malloc() and sq
1b8d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
1b8e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 ** is always ali
1b8f0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 gned to at least
1b900 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 an 8 byte bound
1b910 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 ary, or to a.**
1b920 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 4 byte boundary
1b930 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 if the [SQLITE_4
1b940 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 _BYTE_ALIGNED_MA
1b950 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 LLOC] compile-ti
1b960 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 me.** option is
1b970 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 used..**.** In S
1b980 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1b990 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 5.0 and 3.5.1, i
1b9a0 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 t was possible t
1b9b0 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 o define.** the
1b9c0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
1b9d0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 RY_ALLOCATION wh
1b9e0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 ich would cause
1b9f0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 the built-in.**
1ba00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
1ba10 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
1ba20 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 to be omitted.
1ba30 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 That capability
1ba40 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 .** is no longer
1ba50 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 provided. Only
1ba60 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1ba70 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 allocators can
1ba80 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 be used..**.** P
1ba90 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 rior to SQLite v
1baa0 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 ersion 3.7.10, t
1bab0 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e he Windows OS in
1bac0 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 terface layer ca
1bad0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 lled.** the syst
1bae0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 em malloc() and
1baf0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 free() directly
1bb00 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a when converting.
1bb10 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 ** filenames bet
1bb20 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 ween the UTF-8 e
1bb30 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 ncoding used by
1bb40 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 SQLite.** and wh
1bb50 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 atever filename
1bb60 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 encoding is used
1bb70 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c by the particul
1bb80 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e ar Windows.** in
1bb90 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d stallation. Mem
1bba0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
1bbb0 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 rrors were detec
1bbc0 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 ted, but.** they
1bbd0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 were reported b
1bbe0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 ack as [SQLITE_C
1bbf0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b ANTOPEN] or.** [
1bc00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 SQLITE_IOERR] ra
1bc10 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1bc20 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 E_NOMEM]..**.**
1bc30 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 The pointer argu
1bc40 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 ments to [sqlite
1bc50 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 3_free()] and [s
1bc60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1bc70 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
1bc80 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 her NULL or else
1bc90 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e pointers obtain
1bca0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a ed from a prior.
1bcb0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ** invocation of
1bcc0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1bcd0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1bce0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 realloc()] that
1bcf0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 have.** not yet
1bd00 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a been released..*
1bd10 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
1bd20 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 tion must not re
1bd30 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 ad or write any
1bd40 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f part of.** a blo
1bd50 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 ck of memory aft
1bd60 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 er it has been r
1bd70 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a eleased using.**
1bd80 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1bd90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
1bda0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 alloc()]..*/.voi
1bdb0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
1bdc0 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 c(int);.void *sq
1bdd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f lite3_realloc(vo
1bde0 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 id*, int);.void
1bdf0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 sqlite3_free(voi
1be00 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
1be10 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
1be20 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
1be30 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 s.**.** SQLite p
1be40 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 rovides these tw
1be50 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 o interfaces for
1be60 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 reporting on th
1be70 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 e status.** of t
1be80 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c he [sqlite3_mall
1be90 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f oc()], [sqlite3_
1bea0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 free()], and [sq
1beb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1bec0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 .** routines, wh
1bed0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 ich form the bui
1bee0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
1bef0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
1bf00 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 m..**.** ^The [s
1bf10 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1bf20 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 ed()] routine re
1bf30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
1bf40 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 of bytes.** of
1bf50 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 memory currently
1bf60 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 outstanding (ma
1bf70 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 lloced but not f
1bf80 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b reed)..** ^The [
1bf90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1bfa0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 ighwater()] rout
1bfb0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
1bfc0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 maximum.** value
1bfd0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d of [sqlite3_mem
1bfe0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 ory_used()] sinc
1bff0 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 e the high-water
1c000 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 mark.** was las
1c010 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 t reset. ^The v
1c020 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
1c030 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
1c040 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a y_used()] and.**
1c050 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1c060 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e _highwater()] in
1c070 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 clude any overhe
1c080 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 ad.** added by S
1c090 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 QLite in its imp
1c0a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
1c0b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1c0c0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 ],.** but not ov
1c0d0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 erhead added by
1c0e0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 the any underlyi
1c0f0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 ng system librar
1c100 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 y.** routines th
1c110 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c at [sqlite3_mall
1c120 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a oc()] may call..
1c130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 **.** ^The memor
1c140 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 y high-water mar
1c150 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 k is reset to th
1c160 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
1c170 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d of.** [sqlite3_m
1c180 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 emory_used()] if
1c190 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 and only if the
1c1a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
1c1b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1c1c0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 _highwater()] is
1c1d0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c true. ^The val
1c1e0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ue returned.** b
1c1f0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
1c200 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 y_highwater(1)]
1c210 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 is the high-wate
1c220 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 r mark.** prior
1c230 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f to the reset..*/
1c240 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
1c250 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1c260 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 ed(void);.sqlite
1c270 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
1c280 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1c290 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b (int resetFlag);
1c2a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1c2b0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 : Pseudo-Random
1c2c0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 Number Generator
1c2d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f .**.** SQLite co
1c2e0 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 ntains a high-qu
1c2f0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e ality pseudo-ran
1c300 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 dom number gener
1c310 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 ator (PRNG) used
1c320 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 to.** select ra
1c330 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f ndom [ROWID | RO
1c340 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 WIDs] when inser
1c350 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 ting new records
1c360 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 into a table th
1c370 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 at.** already us
1c380 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 es the largest p
1c390 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e ossible [ROWID].
1c3a0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c The PRNG is al
1c3b0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 so used for.** t
1c3c0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 he build-in rand
1c3d0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 om() and randomb
1c3e0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 lob() SQL functi
1c3f0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 ons. This inter
1c400 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 face allows.** a
1c410 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 pplications to a
1c420 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 ccess the same P
1c430 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 RNG for other pu
1c440 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 rposes..**.** ^A
1c450 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f call to this ro
1c460 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 utine stores N b
1c470 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 ytes of randomne
1c480 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 ss into buffer P
1c490 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
1c4a0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 st time this rou
1c4b0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 tine is invoked
1c4c0 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c (either internal
1c4d0 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 ly or by.** the
1c4e0 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 application) the
1c4f0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 PRNG is seeded
1c500 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
1c510 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
1c520 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 m the xRandomnes
1c530 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
1c540 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
1c550 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
1c560 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 ^On all subsequ
1c570 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c ent invocations,
1c580 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 the pseudo-rand
1c590 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 omness is genera
1c5a0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c ted.** internall
1c5b0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 y and without re
1c5c0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 course to the [s
1c5d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e qlite3_vfs] xRan
1c5e0 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f domness.** metho
1c5f0 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 d..*/.void sqlit
1c600 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e e3_randomness(in
1c610 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a t N, void *P);..
1c620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1c630 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 Compile-Time Aut
1c640 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 horization Callb
1c650 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 acks.**.** ^This
1c660 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 routine registe
1c670 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 rs an authorizer
1c680 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 callback with a
1c690 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
1c6a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1c6b0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 ion], supplied i
1c6c0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
1c6d0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 ment..** ^The au
1c6e0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1c6f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 k is invoked as
1c700 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
1c710 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 re being compile
1c720 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 d.** by [sqlite3
1c730 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
1c740 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c ts variants [sql
1c750 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1c760 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
1c770 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 prepare16()] and
1c780 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1c790 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 e16_v2()]. ^At
1c7a0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
1c7b0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
1c7c0 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
1c7d0 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
1c7e0 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
1c7f0 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
1c800 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
1c810 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1c820 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
1c830 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
1c840 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
1c850 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 owed. ^The auth
1c860 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1c870 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
1c880 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 [SQLITE_OK] to
1c890 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e allow the action
1c8a0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 , [SQLITE_IGNORE
1c8b0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 ] to disallow th
1c8c0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 e.** specific ac
1c8d0 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 tion but allow t
1c8e0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1c8f0 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 to continue to
1c900 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 be.** compiled,
1c910 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
1c920 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e to cause the en
1c930 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 tire SQL stateme
1c940 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 nt to be.** reje
1c950 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 cted with an err
1c960 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 or. ^If the aut
1c970 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1c980 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
1c990 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
1c9a0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1c9b0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
1c9c0 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a r [SQLITE_DENY].
1c9d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c ** then the [sql
1c9e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1c9f0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
1ca00 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
1ca10 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 ered.** the auth
1ca20 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
1ca30 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
1ca40 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 essage..**.** Wh
1ca50 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
1ca60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1ca70 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 OK], that means
1ca80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
1ca90 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b requested is ok
1caa0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c . ^When the cal
1cab0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
1cac0 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 QLITE_DENY], the
1cad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1cae0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
1caf0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
1cb00 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
1cb10 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 .** authorizer w
1cb20 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
1cb30 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 error message e
1cb40 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a xplaining that.*
1cb50 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 * access is deni
1cb60 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ed. .**.** ^The
1cb70 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1cb80 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
1cb90 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 r callback is a
1cba0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 copy of the thir
1cbb0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
1cbc0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 o the sqlite3_se
1cbd0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 t_authorizer() i
1cbe0 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 nterface. ^The s
1cbf0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
1cc00 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
1cc10 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
1cc20 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 [SQLITE_COPY |
1cc30 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 action code] tha
1cc40 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 t specifies.** t
1cc50 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 he particular ac
1cc60 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
1cc70 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 rized. ^The thir
1cc80 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 d through sixth
1cc90 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
1cca0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 the callback ar
1ccb0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 e zero-terminate
1ccc0 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 d strings that c
1ccd0 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 ontain additiona
1cce0 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f l.** details abo
1ccf0 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f ut the action to
1cd00 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a be authorized..
1cd10 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 **.** ^If the ac
1cd20 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
1cd30 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e LITE_READ].** an
1cd40 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
1cd50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 eturns [SQLITE_I
1cd60 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a GNORE] then the.
1cd70 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
1cd80 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e tement] statemen
1cd90 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 t is constructed
1cda0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a to substitute.*
1cdb0 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 * a NULL value i
1cdc0 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 n place of the t
1cdd0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
1cde0 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 would have.** b
1cdf0 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c een read if [SQL
1ce00 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e ITE_OK] had been
1ce10 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
1ce20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a [SQLITE_IGNORE].
1ce30 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 ** return can be
1ce40 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e used to deny an
1ce50 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 untrusted user
1ce60 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 access to indivi
1ce70 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 dual.** columns
1ce80 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e of a table..** ^
1ce90 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
1cea0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 de is [SQLITE_DE
1ceb0 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 LETE] and the ca
1cec0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a llback returns.*
1ced0 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 * [SQLITE_IGNORE
1cee0 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 ] then the [DELE
1cef0 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 TE] operation pr
1cf00 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a oceeds but the.*
1cf10 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 * [truncate opti
1cf20 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 mization] is dis
1cf30 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f abled and all ro
1cf40 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 ws are deleted i
1cf50 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a ndividually..**.
1cf60 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 ** An authorizer
1cf70 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 is used when [s
1cf80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c qlite3_prepare |
1cf90 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 preparing].** S
1cfa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 QL statements fr
1cfb0 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 om an untrusted
1cfc0 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 source, to ensur
1cfd0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 e that the SQL s
1cfe0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 tatements.** do
1cff0 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 not try to acces
1d000 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 s data they are
1d010 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 not allowed to s
1d020 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 ee, or that they
1d030 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 do not.** try t
1d040 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 o execute malici
1d050 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 ous statements t
1d060 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 hat damage the d
1d070 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a atabase. For.**
1d080 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 example, an app
1d090 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c lication may all
1d0a0 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 ow a user to ent
1d0b0 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 er arbitrary.**
1d0c0 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 SQL queries for
1d0d0 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 evaluation by a
1d0e0 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 database. But t
1d0f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
1d100 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 oes.** not want
1d110 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 the user to be a
1d120 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 ble to make arbi
1d130 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f trary changes to
1d140 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
1d150 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 . An authorizer
1d160 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 could then be p
1d170 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c ut in place whil
1d180 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e e the.** user-en
1d190 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 tered SQL is bei
1d1a0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
1d1b0 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 are | prepared]
1d1c0 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 that.** disallow
1d1d0 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 s everything exc
1d1e0 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 ept [SELECT] sta
1d1f0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 tements..**.** A
1d200 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
1d210 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 need to process
1d220 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 SQL from untrus
1d230 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d ted sources.** m
1d240 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 ight also consid
1d250 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f er lowering reso
1d260 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e urce limits usin
1d270 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
1d280 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 ()].** and limit
1d290 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a ing database siz
1d2a0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 e using the [max
1d2b0 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 _page_count] [PR
1d2c0 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 AGMA].** in addi
1d2d0 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e tion to using an
1d2e0 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a authorizer..**.
1d2f0 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 ** ^(Only a sing
1d300 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 le authorizer ca
1d310 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e n be in place on
1d320 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
1d330 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 ection.** at a t
1d340 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 ime. Each call
1d350 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
1d360 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 uthorizer overri
1d370 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 des the.** previ
1d380 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 ous call.)^ ^Di
1d390 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 sable the author
1d3a0 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 izer by installi
1d3b0 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 ng a NULL callba
1d3c0 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f ck..** The autho
1d3d0 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 rizer is disable
1d3e0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a d by default..**
1d3f0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
1d400 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 er callback must
1d410 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
1d420 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
1d430 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
1d440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
1d450 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 t invoked the au
1d460 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1d470 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 k..** Note that
1d480 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1d490 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
1d4a0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
1d4b0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
1d4c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1d4d0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
1d4e0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
1d4f0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
1d500 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e aph..**.** ^When
1d510 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1d520 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 e_v2()] is used
1d530 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 to prepare a sta
1d540 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 tement, the.** s
1d550 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 tatement might b
1d560 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 e re-prepared du
1d570 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 ring [sqlite3_st
1d580 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a ep()] due to a .
1d590 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 ** schema change
1d5a0 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 . Hence, the ap
1d5b0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
1d5c0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
1d5d0 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 .** correct auth
1d5e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1d5f0 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 remains in place
1d600 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c during the [sql
1d610 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a ite3_step()]..**
1d620 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 .** ^Note that t
1d630 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1d640 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
1d650 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a d only during.**
1d660 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1d670 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
1d680 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 ants. Authoriza
1d690 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 tion is not.** p
1d6a0 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 erformed during
1d6b0 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 statement evalua
1d6c0 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 tion in [sqlite3
1d6d0 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 _step()], unless
1d6e0 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e .** as stated in
1d6f0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 the previous pa
1d700 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 ragraph, sqlite3
1d710 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a _step() invokes.
1d720 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ** sqlite3_prepa
1d730 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 re_v2() to repre
1d740 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
1d750 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 after a schema
1d760 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 change..*/.int s
1d770 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1d780 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 rizer(. sqlite3
1d790 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 *,. int (*xAuth
1d7a0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
1d7b0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1d7c0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1d7d0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 const char*),.
1d7e0 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a void *pUserData.
1d7f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1d800 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 EF: Authorizer R
1d810 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a eturn Codes.**.*
1d820 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 * The [sqlite3_s
1d830 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 et_authorizer |
1d840 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1d850 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 ack function] mu
1d860 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 st.** return eit
1d870 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 her [SQLITE_OK]
1d880 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 or one of these
1d890 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e two constants in
1d8a0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 order.** to sig
1d8b0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 nal SQLite wheth
1d8c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 er or not the ac
1d8d0 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
1d8e0 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b d. See the.** [
1d8f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1d900 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
1d910 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f zer documentatio
1d920 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 n] for additiona
1d930 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
1d940 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
1d950 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 t SQLITE_IGNORE
1d960 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 is also used as
1d970 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 a [SQLITE_ROLLBA
1d980 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 CK | return code
1d990 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 ].** from the [s
1d9a0 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 qlite3_vtab_on_c
1d9b0 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 onflict()] inter
1d9c0 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 face..*/.#define
1d9d0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 SQLITE_DENY 1
1d9e0 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 /* Abort the
1d9f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 SQL statement wi
1da00 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 th an error */.#
1da10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 define SQLITE_IG
1da20 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 NORE 2 /* Don'
1da30 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 t allow access,
1da40 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 but don't genera
1da50 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a te an error */..
1da60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1da70 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f Authorizer Actio
1da80 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 n Codes.**.** Th
1da90 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
1daa0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 uthorizer()] int
1dab0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 erface registers
1dac0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
1dad0 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 tion.** that is
1dae0 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f invoked to autho
1daf0 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c rize certain SQL
1db00 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f statement actio
1db10 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f ns. The.** seco
1db20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
1db30 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
1db40 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 an integer code
1db50 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
1db60 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 * what action is
1db70 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 being authorize
1db80 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 d. These are th
1db90 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e e integer action
1dba0 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 codes that.** t
1dbb0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
1dbc0 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 llback may be pa
1dbd0 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ssed..**.** Thes
1dbe0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 e action code va
1dbf0 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 lues signify wha
1dc00 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 t kind of operat
1dc10 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 ion is to be.**
1dc20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
1dc30 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 3rd and 4th par
1dc40 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 ameters to the a
1dc50 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 uthorization.**
1dc60 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1dc70 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 n will be parame
1dc80 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 ters or NULL dep
1dc90 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 ending on which
1dca0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 of these.** code
1dcb0 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 s is used as the
1dcc0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1dcd0 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 r. ^(The 5th pa
1dce0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a rameter to the.*
1dcf0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c * authorizer cal
1dd00 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d lback is the nam
1dd10 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
1dd20 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 e ("main", "temp
1dd30 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 ",.** etc.) if a
1dd40 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 pplicable.)^ ^T
1dd50 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 he 6th parameter
1dd60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
1dd70 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 er callback.** i
1dd80 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
1dd90 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 e inner-most tri
1dda0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 gger or view tha
1ddb0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 t is responsible
1ddc0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 for.** the acce
1ddd0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 ss attempt or NU
1dde0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 LL if this acces
1ddf0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 s attempt is dir
1de00 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f ectly from.** to
1de10 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 p-level SQL code
1de20 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ..*/./**********
1de30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1de40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1de50 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a * 3rd **********
1de60 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a ** 4th *********
1de70 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 **/.#define SQLI
1de80 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 TE_CREATE_INDEX
1de90 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 1 /*
1dea0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
1deb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1dec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ded0 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 E_CREATE_TABLE
1dee0 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 2 /* T
1def0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1df00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1df10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1df20 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 _CREATE_TEMP_IND
1df30 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e EX 3 /* In
1df40 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1df50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1df60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1df70 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c CREATE_TEMP_TABL
1df80 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 E 4 /* Tab
1df90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1dfa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1dfb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1dfc0 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 REATE_TEMP_TRIGG
1dfd0 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 ER 5 /* Trig
1dfe0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
1dff0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1e000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1e010 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 EATE_TEMP_VIEW
1e020 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 6 /* View
1e030 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1e040 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1e050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1e060 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 ATE_TRIGGER
1e070 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 7 /* Trigge
1e080 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1e090 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1e0a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1e0b0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 TE_VIEW
1e0c0 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 8 /* View Na
1e0d0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1e0e0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1e0f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 ine SQLITE_DELET
1e100 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
1e110 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 9 /* Table Na
1e120 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1e130 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1e140 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 ne SQLITE_DROP_I
1e150 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 NDEX 1
1e160 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 0 /* Index Nam
1e170 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
1e180 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1e190 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 e SQLITE_DROP_TA
1e1a0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 BLE 11
1e1b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1e1c0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1e1d0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1e1e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
1e1f0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 P_INDEX 12
1e200 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
1e210 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
1e220 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e230 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
1e240 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 _TABLE 13
1e250 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1e260 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1e270 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1e280 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
1e290 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 TRIGGER 14
1e2a0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
1e2b0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1e2c0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e2d0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 LITE_DROP_TEMP_V
1e2e0 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f IEW 15 /
1e2f0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
1e300 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1e310 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e320 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 ITE_DROP_TRIGGER
1e330 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 16 /*
1e340 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
1e350 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1e360 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e370 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 TE_DROP_VIEW
1e380 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 17 /*
1e390 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
1e3a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1e3b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e3c0 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 E_INSERT
1e3d0 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 18 /* T
1e3e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
1e3f0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1e400 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e410 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 _PRAGMA
1e420 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 19 /* Pr
1e430 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 agma Name 1s
1e440 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f t arg or NULL */
1e450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e460 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 READ
1e470 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 20 /* Tab
1e480 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
1e490 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
1e4a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
1e4b0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 ELECT
1e4c0 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 21 /* NULL
1e4d0 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
1e4e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1e4f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 define SQLITE_TR
1e500 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 ANSACTION
1e510 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 22 /* Opera
1e520 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 tion NULL
1e530 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1e540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 efine SQLITE_UPD
1e550 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ATE
1e560 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 23 /* Table
1e570 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
1e580 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1e590 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 fine SQLITE_ATTA
1e5a0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CH
1e5b0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 24 /* Filenam
1e5c0 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 e NULL
1e5d0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1e5e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 ine SQLITE_DETAC
1e5f0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
1e600 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 25 /* Database
1e610 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 Name NULL
1e620 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1e630 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f ne SQLITE_ALTER_
1e640 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 TABLE 2
1e650 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6 /* Database
1e660 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d Name Table Nam
1e670 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1e680 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 e SQLITE_REINDEX
1e690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 27
1e6a0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1e6b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1e6c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1e6d0 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 SQLITE_ANALYZE
1e6e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 28
1e6f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1e700 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1e710 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e720 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 SQLITE_CREATE_VT
1e730 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 ABLE 29
1e740 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1e750 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 Module Name
1e760 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1e770 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c QLITE_DROP_VTABL
1e780 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 E 30
1e790 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1e7a0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 Module Name
1e7b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e7c0 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 LITE_FUNCTION
1e7d0 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 31 /
1e7e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
1e7f0 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 Function Name
1e800 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e810 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 ITE_SAVEPOINT
1e820 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 32 /*
1e830 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
1e840 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 Savepoint Name
1e850 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e860 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 TE_COPY
1e870 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 0 /*
1e880 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a No longer used *
1e890 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
1e8a0 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 F: Tracing And P
1e8b0 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f rofiling Functio
1e8c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
1e8d0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 outines register
1e8e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1e8f0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 ons that can be
1e900 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 used for.** trac
1e910 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e ing and profilin
1e920 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 g the execution
1e930 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
1e940 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 s..**.** ^The ca
1e950 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1e960 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
1e970 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 lite3_trace() is
1e980 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 invoked at.** v
1e990 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 arious times whe
1e9a0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
1e9b0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 nt is being run
1e9c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 by [sqlite3_step
1e9d0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ()]..** ^The sql
1e9e0 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c ite3_trace() cal
1e9f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
1ea00 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 with a UTF-8 re
1ea10 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a ndering of the.*
1ea20 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 * SQL statement
1ea30 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 text as the stat
1ea40 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 ement first begi
1ea50 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a ns executing..**
1ea60 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 ^(Additional sq
1ea70 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 lite3_trace() ca
1ea80 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 llbacks might oc
1ea90 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 cur.** as each t
1eaa0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 riggered subprog
1eab0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 ram is entered.
1eac0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 The callbacks f
1ead0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 or triggers.** c
1eae0 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 ontain a UTF-8 S
1eaf0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 QL comment that
1eb00 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 identifies the t
1eb10 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 rigger.)^.**.**
1eb20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
1eb30 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
1eb40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f d by sqlite3_pro
1eb50 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 file() is invoke
1eb60 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c d.** as each SQL
1eb70 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 statement finis
1eb80 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 hes. ^The profi
1eb90 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 le callback cont
1eba0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 ains.** the orig
1ebb0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 inal statement t
1ebc0 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d ext and an estim
1ebd0 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 ate of wall-cloc
1ebe0 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 k time.** of how
1ebf0 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 long that state
1ec00 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e ment took to run
1ec10 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 . ^The profile
1ec20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 callback.** time
1ec30 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 is in units of
1ec40 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 nanoseconds, how
1ec50 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 ever the current
1ec60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a implementation.
1ec70 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 ** is only capab
1ec80 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e le of millisecon
1ec90 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 d resolution so
1eca0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 the six least si
1ecb0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 gnificant.** dig
1ecc0 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 its in the time
1ecd0 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e are meaningless.
1ece0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
1ecf0 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d s of SQLite.** m
1ed00 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 ight provide gre
1ed10 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 ater resolution
1ed20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 on the profiler
1ed30 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a callback. The.*
1ed40 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c * sqlite3_profil
1ed50 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
1ed60 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 considered exper
1ed70 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a imental and is.*
1ed80 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 * subject to cha
1ed90 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 nge in future ve
1eda0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1edb0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
1edc0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 e3_trace(sqlite3
1edd0 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 *, void(*xTrace)
1ede0 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 (void*,const cha
1edf0 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c r*), void*);.SQL
1ee00 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c ITE_EXPERIMENTAL
1ee10 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
1ee20 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
1ee30 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
1ee40 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
1ee50 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
1ee60 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
1ee70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1ee80 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 Query Progress C
1ee90 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e allbacks.**.** ^
1eea0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 The sqlite3_prog
1eeb0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e ress_handler(D,N
1eec0 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 ,X,P) interface
1eed0 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 causes the callb
1eee0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
1eef0 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 X to be invoked
1ef00 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 periodically dur
1ef10 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 ing long running
1ef20 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
1ef30 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b lite3_exec()], [
1ef40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1ef50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 and [sqlite3_get
1ef60 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a _table()] for.**
1ef70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1ef80 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d tion D. An exam
1ef90 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 ple use for this
1efa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
1efb0 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 to keep a GUI u
1efc0 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 pdated during a
1efd0 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a large query..**.
1efe0 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 ** ^The paramete
1eff0 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 r P is passed th
1f000 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c rough as the onl
1f010 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 y parameter to t
1f020 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 he .** callback
1f030 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 function X. ^Th
1f040 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 e parameter N is
1f050 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a the number of .
1f060 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 ** [virtual mach
1f070 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 ine instructions
1f080 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 ] that are evalu
1f090 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 ated between suc
1f0a0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 cessive.** invoc
1f0b0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 ations of the ca
1f0c0 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 llback X..**.**
1f0d0 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 ^Only a single p
1f0e0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
1f0f0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 may be defined a
1f100 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a t one time per.*
1f110 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1f120 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 ection]; setting
1f130 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 a new progress
1f140 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 handler cancels
1f150 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 the.** old one.
1f160 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 ^Setting parame
1f170 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 ter X to NULL di
1f180 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 sables the progr
1f190 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 ess handler..**
1f1a0 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 ^The progress ha
1f1b0 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 ndler is also di
1f1c0 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e sabled by settin
1f1d0 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c g N to a value l
1f1e0 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a ess.** than 1..*
1f1f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f *.** ^If the pro
1f200 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 gress callback r
1f210 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
1f220 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 the operation i
1f230 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 s.** interrupted
1f240 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 . This feature
1f250 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 can be used to i
1f260 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 mplement a.** "C
1f270 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e ancel" button on
1f280 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 a GUI progress
1f290 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a dialog box..**.*
1f2a0 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 * The progress h
1f2b0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 andler callback
1f2c0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
1f2d0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
1f2e0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
1f2f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1f300 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
1f310 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
1f320 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 er..** Note that
1f330 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f340 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
1f350 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
1f360 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
1f370 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
1f380 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
1f390 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
1f3a0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
1f3b0 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 raph..**.*/.void
1f3c0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 sqlite3_progres
1f3d0 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 s_handler(sqlite
1f3e0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 3*, int, int(*)(
1f3f0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a void*), void*);.
1f400 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1f410 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 Opening A New D
1f420 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
1f430 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 on.**.** ^These
1f440 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e routines open an
1f450 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
1f460 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 file as specifi
1f470 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 ed by the .** fi
1f480 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e lename argument.
1f490 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 ^The filename a
1f4a0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 rgument is inter
1f4b0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 preted as UTF-8
1f4c0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
1f4d0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
1f4e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 3_open_v2() and
1f4f0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 as UTF-16 in the
1f500 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 native byte.**
1f510 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 order for sqlite
1f520 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 3_open16(). ^(A
1f530 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1f540 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 tion] handle is
1f550 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 usually.** retur
1f560 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 ned in *ppDb, ev
1f570 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f en if an error o
1f580 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 ccurs. The only
1f590 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 exception is th
1f5a0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 at.** if SQLite
1f5b0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
1f5c0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
1f5d0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 hold the [sqlite
1f5e0 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 3] object,.** a
1f5f0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 NULL will be wri
1f600 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 tten into *ppDb
1f610 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 instead of a poi
1f620 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c nter to the [sql
1f630 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e ite3].** object.
1f640 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 )^ ^(If the data
1f650 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
1f660 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 and/or created)
1f670 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 successfully, th
1f680 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b en.** [SQLITE_OK
1f690 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
1f6a0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
1f6b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
1f6c0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a urned.)^ ^The.**
1f6d0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1f6e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
1f6f0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 errmsg16()] rout
1f700 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 ines can be used
1f710 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e to obtain.** an
1f720 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 English languag
1f730 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 e description of
1f740 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f the error follo
1f750 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f wing a failure o
1f760 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 f any.** of the
1f770 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 sqlite3_open() r
1f780 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
1f790 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
1f7a0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 ding for the dat
1f7b0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 abase will be UT
1f7c0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 F-8 if.** sqlite
1f7d0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
1f7e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
1f7f0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 called and.** U
1f800 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
1f810 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 ive byte order i
1f820 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 f sqlite3_open16
1f830 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a () is used..**.*
1f840 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 * Whether or not
1f850 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
1f860 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e when it is open
1f870 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a ed, resources.**
1f880 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
1f890 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
1f8a0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c onnection] handl
1f8b0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 e should be rele
1f8c0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 ased by.** passi
1f8d0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
1f8e0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 3_close()] when
1f8f0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 it is no longer
1f900 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
1f910 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e The sqlite3_open
1f920 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 _v2() interface
1f930 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 works like sqlit
1f940 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 e3_open().** exc
1f950 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 ept that it acce
1f960 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e pts two addition
1f970 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f al parameters fo
1f980 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e r additional con
1f990 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 trol.** over the
1f9a0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f new database co
1f9b0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 nnection. ^(The
1f9c0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 flags parameter
1f9d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f to.** sqlite3_o
1f9e0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b pen_v2() can tak
1f9f0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 e one of.** the
1fa00 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 following three
1fa10 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c values, optional
1fa20 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 ly combined with
1fa30 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 the .** [SQLITE
1fa40 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 _OPEN_NOMUTEX],
1fa50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
1fa60 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 LMUTEX], [SQLITE
1fa70 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
1fa80 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f E],.** [SQLITE_O
1fa90 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
1faa0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 ], and/or [SQLIT
1fab0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
1fac0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a s:)^.**.** <dl>.
1fad0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
1fae0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c _OPEN_READONLY]<
1faf0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1fb00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1fb10 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 ed in read-only
1fb20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 mode. If the da
1fb30 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a tabase does not.
1fb40 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ** already exist
1fb50 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 , an error is re
1fb60 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
1fb70 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
1fb80 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
1fb90 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
1fba0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
1fbb0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
1fbc0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 g and writing if
1fbd0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 possible, or re
1fbe0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 ading.** only if
1fbf0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 the file is wri
1fc00 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 te protected by
1fc10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
1fc20 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 stem. In either
1fc30 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 .** case the dat
1fc40 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 abase must alrea
1fc50 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 dy exist, otherw
1fc60 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 ise an error is
1fc70 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
1fc80 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
1fc90 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
1fca0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
1fcb0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e PEN_CREATE]</dt>
1fcc0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
1fcd0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
1fce0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 or reading and w
1fcf0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 riting, and is c
1fd00 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 reated if.** it
1fd10 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 does not already
1fd20 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 exist. This is
1fd30 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 the behavior tha
1fd40 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 t is always used
1fd50 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
1fd60 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
1fd70 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 e3_open16().</dd
1fd80 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a >)^.** </dl>.**.
1fd90 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 ** If the 3rd pa
1fda0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
1fdb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
1fdc0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a not one of the.*
1fdd0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 * combinations s
1fde0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f hown above optio
1fdf0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 nally combined w
1fe00 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 ith other.** [SQ
1fe10 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
1fe20 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e LY | SQLITE_OPEN
1fe30 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e _* bits].** then
1fe40 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
1fe50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
1fe60 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
1fe70 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 E_OPEN_NOMUTEX]
1fe80 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 flag is set, the
1fe90 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
1fea0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 onnection.** ope
1feb0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d ns in the multi-
1fec0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
1fed0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 g mode] as long
1fee0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 as the single-th
1fef0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 read.** mode has
1ff00 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 not been set at
1ff10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
1ff20 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 start-time. ^I
1ff30 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 f the.** [SQLITE
1ff40 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d _OPEN_FULLMUTEX]
1ff50 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 flag is set the
1ff60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
1ff70 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a onnection opens.
1ff80 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c ** in the serial
1ff90 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
1ffa0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e mode] unless sin
1ffb0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a gle-thread was.*
1ffc0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c * previously sel
1ffd0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 ected at compile
1ffe0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
1fff0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ime..** ^The [SQ
20000 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
20010 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
20020 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
20030 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 connection to be
20040 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 .** eligible to
20050 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 use [shared cach
20060 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c e mode], regardl
20070 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
20080 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 r not shared.**
20090 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 cache is enabled
200a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
200b0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 enable_shared_ca
200c0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a che()]. ^The.**
200d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
200e0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 IVATECACHE] flag
200f0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 causes the data
20100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
20110 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 to not.** partic
20120 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 ipate in [shared
20130 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 cache mode] eve
20140 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c n if it is enabl
20150 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
20160 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
20170 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
20180 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 v2() is the name
20190 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
201a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 te3_vfs] object
201b0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 that defines the
201c0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
201d0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 m interface that
201e0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 .** the new data
201f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
20200 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 should use. ^If
20210 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
20220 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 meter is.** a NU
20230 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
20240 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
20250 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
20260 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
20270 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
20280 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 is ":memory:",
20290 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 then a private,
202a0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d temporary in-mem
202b0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ory database.**
202c0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 is created for t
202d0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 he connection.
202e0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 ^This in-memory
202f0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 database will va
20300 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 nish when.** the
20310 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
20320 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 tion is closed.
20330 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 Future versions
20340 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 of SQLite might
20350 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 .** make use of
20360 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 additional speci
20370 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 al filenames tha
20380 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 t begin with the
20390 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a ":" character..
203a0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 ** It is recomme
203b0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 nded that when a
203c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 database filena
203d0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 me actually does
203e0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 begin with.** a
203f0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 ":" character y
20400 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 ou should prefix
20410 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 the filename wi
20420 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 th a pathname su
20430 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f ch as.** "./" to
20440 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 avoid ambiguity
20450 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
20460 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 filename is an e
20470 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 mpty string, the
20480 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d n a private, tem
20490 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 porary.** on-dis
204a0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 k database will
204b0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 be created. ^Th
204c0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 is private datab
204d0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 ase will be.** a
204e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c utomatically del
204f0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 eted as soon as
20500 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
20510 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 nection is close
20520 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 d..**.** [[URI f
20530 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 ilenames in sqli
20540 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 te3_open()]] <h3
20550 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f >URI Filenames</
20560 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 h3>.**.** ^If [U
20570 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 RI filename] int
20580 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
20590 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 nabled, and the
205a0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
205b0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 t.** begins with
205c0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 "file:", then t
205d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 he filename is i
205e0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
205f0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c URI. ^URI.** fil
20600 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
20610 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 tion is enabled
20620 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f if the [SQLITE_O
20630 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
20640 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 .** set in the f
20650 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 ourth argument t
20660 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
20670 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 2(), or if it ha
20680 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 s.** been enable
20690 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 d globally using
206a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
206b0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 FIG_URI] option
206c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c with the.** [sql
206d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d ite3_config()] m
206e0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 ethod or by the
206f0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d [SQLITE_USE_URI]
20700 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
20710 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 tion..** As of S
20720 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
20730 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 7.7, URI filenam
20740 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
20750 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a is turned off.*
20760 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 * by default, bu
20770 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 t future release
20780 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
20790 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c t enable URI fil
207a0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 ename.** interpr
207b0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 etation by defau
207c0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 lt. See "[URI f
207d0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 ilenames]" for a
207e0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
207f0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
20800 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 URI filenames ar
20810 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 e parsed accordi
20820 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 ng to RFC 3986.
20830 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 ^If the URI cont
20840 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f ains an.** autho
20850 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 rity, then it mu
20860 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 st be either an
20870 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
20880 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 the string .** "
20890 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 localhost". ^If
208a0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 the authority is
208b0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 not an empty st
208c0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f ring or "localho
208d0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f st", an .** erro
208e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f r is returned to
208f0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 the caller. ^Th
20900 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f e fragment compo
20910 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 nent of a URI, i
20920 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 f .** present, i
20930 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
20940 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 ^SQLite uses th
20950 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 e path component
20960 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 of the URI as t
20970 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
20980 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 isk file.** whic
20990 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 h contains the d
209a0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 atabase. ^If the
209b0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 path begins wit
209c0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 h a '/' characte
209d0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 r, .** then it i
209e0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 s interpreted as
209f0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 an absolute pat
20a00 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 h. ^If the path
20a10 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a does not begin .
20a20 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d ** with a '/' (m
20a30 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 eaning that the
20a40 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f authority sectio
20a50 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f n is omitted fro
20a60 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 m the URI).** th
20a70 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 en the path is i
20a80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
20a90 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a relative path. .
20aa0 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 ** ^On windows,
20ab0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e the first compon
20ac0 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 ent of an absolu
20ad0 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 te path .** is a
20ae0 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 drive specifica
20af0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 tion (e.g. "C:")
20b00 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 ..**.** [[core U
20b10 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 RI query paramet
20b20 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 ers]].** The que
20b30 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 ry component of
20b40 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 a URI may contai
20b50 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 n parameters tha
20b60 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 t are interprete
20b70 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 d.** either by S
20b80 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 QLite itself, or
20b90 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 by a [VFS | cus
20ba0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e tom VFS implemen
20bb0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 tation]..** SQLi
20bc0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 te interprets th
20bd0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
20be0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
20bf0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a rs:.**.** <ul>.*
20c00 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c * <li> <b>vfs<
20c10 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 /b>: ^The "vfs"
20c20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
20c30 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 used to specify
20c40 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 the name of.**
20c50 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 a VFS object
20c60 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 that provides t
20c70 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
20c80 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
20c90 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 at should.**
20ca0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 be used to acce
20cb0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
20cc0 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 file on disk. ^I
20cd0 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 f this option is
20ce0 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 set to.** a
20cf0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 n empty string t
20d00 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f he default VFS o
20d10 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e bject is used. ^
20d20 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e Specifying an un
20d30 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 known.** VFS
20d40 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 is an error. ^I
20d50 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 f sqlite3_open_v
20d60 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 2() is used and
20d70 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 the vfs option i
20d80 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 s.** present
20d90 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 , then the VFS s
20da0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
20db0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 option takes pre
20dc0 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 cedence over.**
20dd0 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 the value pa
20de0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 ssed as the four
20df0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
20e00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
20e10 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 )..**.** <li>
20e20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 <b>mode</b>: ^(T
20e30 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 he mode paramete
20e40 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 r may be set to
20e50 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 either "ro", "rw
20e60 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c ",.** "rwc",
20e70 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 or "memory". At
20e80 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 tempting to set
20e90 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 it to any other
20ea0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 value is.**
20eb0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 an error)^. .**
20ec0 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 ^If "ro" is
20ed0 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 specified, then
20ee0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
20ef0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d opened for read-
20f00 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 only .** acc
20f10 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 ess, just as if
20f20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
20f30 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 _READONLY] flag
20f40 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 had been set in
20f50 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 the .** thir
20f60 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 d argument to sq
20f70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
20f80 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 ^If the mode op
20f90 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a tion is set to .
20fa0 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 ** "rw", the
20fb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
20fc0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
20fd0 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 d-write (but not
20fe0 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 create) .**
20ff0 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 access, as if S
21000 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
21010 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 RITE (but not SQ
21020 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
21030 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 ) had .** be
21040 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 en set. ^Value "
21050 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 rwc" is equivale
21060 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f nt to setting bo
21070 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 th .** SQLIT
21080 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
21090 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e and SQLITE_OPEN
210a0 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 _CREATE. ^If th
210b0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 e mode option is
210c0 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 .** set to "
210d0 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 memory" then a p
210e0 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 ure [in-memory d
210f0 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 atabase] that ne
21100 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 ver reads.**
21110 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 or writes from
21120 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 disk is used. ^I
21130 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f t is an error to
21140 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 specify a value
21150 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 for.** the
21160 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 mode parameter t
21170 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 hat is less rest
21180 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 rictive than tha
21190 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a t specified by.*
211a0 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 * the flags
211b0 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 passed in the th
211c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
211d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
211e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e ()..**.** <li>
211f0 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e <b>cache</b>: ^
21200 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 The cache parame
21210 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 ter may be set t
21220 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 o either "shared
21230 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 " or.** "pri
21240 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 vate". ^Setting
21250 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 it to "shared" i
21260 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 s equivalent to
21270 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 setting the.**
21280 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 SQLITE_OPEN_S
21290 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 HAREDCACHE bit i
212a0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 n the flags argu
212b0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a ment passed to.*
212c0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 * sqlite3_op
212d0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e en_v2(). ^Settin
212e0 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 g the cache para
212f0 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 meter to "privat
21300 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 e" is .** eq
21310 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
21320 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f ing the SQLITE_O
21330 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
21340 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 bit..** ^If
21350 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
21360 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 () is used and t
21370 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d he "cache" param
21380 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 eter is present
21390 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 in.** a URI
213a0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 filename, its va
213b0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e lue overrides an
213c0 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 y behavior reque
213d0 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a sted by setting.
213e0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
213f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
21400 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 or SQLITE_OPEN_S
21410 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e HAREDCACHE flag.
21420 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
21430 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 ^Specifying an u
21440 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 nknown parameter
21450 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f in the query co
21460 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
21470 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 is not an.** er
21480 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 ror. Future ver
21490 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
214a0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 might understand
214b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 additional quer
214c0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e y.** parameters.
214d0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 See "[query pa
214e0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 rameters with sp
214f0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f ecial meaning to
21500 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a SQLite]" for.**
21510 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
21520 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b rmation..**.** [
21530 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 [URI filename ex
21540 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 amples]] <h3>URI
21550 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c filename exampl
21560 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 es</h3>.**.** <t
21570 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 able border="1"
21580 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c align=center cel
21590 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c lpadding=5>.** <
215a0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 tr><th> URI file
215b0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c names <th> Resul
215c0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 ts.** <tr><td> f
215d0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e ile:data.db <td>
215e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
215f0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 en the file "dat
21600 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 a.db" in the cur
21610 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a rent directory..
21620 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
21630 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
21640 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 .db<br>.**
21650 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 file:///home
21660 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 /fred/data.db <b
21670 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 r> .**
21680 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 file://localhost
21690 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
216a0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a db <br> <td> .**
216b0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 Open t
216c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
216d0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 "/home/fred/dat
216e0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 a.db"..** <tr><t
216f0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 d> file://darkst
21700 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ar/home/fred/dat
21710 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
21720 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e An error.
21730 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e "darkstar" is n
21740 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 ot a recognized
21750 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 authority..** <t
21760 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 r><td style="whi
21770 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 te-space:nowrap"
21780 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 > .** f
21790 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 ile:///C:/Docume
217a0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 nts%20and%20Sett
217b0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f ings/fred/Deskto
217c0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 p/data.db.**
217d0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e <td> Windows on
217e0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c ly: Open the fil
217f0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 e "data.db" on f
21800 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e red's desktop on
21810 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 drive.**
21820 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 C:. Note that
21830 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e the %20 escapin
21840 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c g in this exampl
21850 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c e is not strictl
21860 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e y .** n
21870 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 ecessary - space
21880 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 characters can
21890 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c be used literall
218a0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e y.** in
218b0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a URI filenames..
218c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
218d0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f :data.db?mode=ro
218e0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c &cache=private <
218f0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
21900 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 Open file "data
21910 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 .db" in the curr
21920 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f ent directory fo
21930 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 r read-only acce
21940 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ss..**
21950 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
21960 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
21970 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 red-cache mode i
21980 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 s enabled by.**
21990 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 default
219a0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 , use a private
219b0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 cache..** <tr><t
219c0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
219d0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 ed/data.db?vfs=u
219e0 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a nix-nolock <td>.
219f0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
21a00 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 file "/home/fre
21a10 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 d/data.db". Use
21a20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 the special VFS
21a30 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a "unix-nolock"..*
21a40 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
21a50 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 data.db?mode=rea
21a60 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 donly <td> .**
21a70 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 An error
21a80 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 . "readonly" is
21a90 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 not a valid opti
21aa0 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 on for the "mode
21ab0 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 " parameter..**
21ac0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e </table>.**.** ^
21ad0 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 URI hexadecimal
21ae0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 escape sequences
21af0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f (%HH) are suppo
21b00 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 rted within the
21b10 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 path and.** quer
21b20 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 y components of
21b30 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 a URI. A hexadec
21b40 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
21b50 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 ence consists of
21b60 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 a.** percent si
21b70 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f gn - "%" - follo
21b80 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 wed by exactly t
21b90 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 wo hexadecimal d
21ba0 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 igits .** specif
21bb0 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 ying an octet va
21bc0 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 lue. ^Before the
21bd0 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 path or query c
21be0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a omponents of a.*
21bf0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 * URI filename a
21c00 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 re interpreted,
21c10 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 they are encoded
21c20 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 using UTF-8 and
21c30 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 all .** hexadec
21c40 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
21c50 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 ences replaced b
21c60 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 y a single byte
21c70 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a containing the.*
21c80 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 * corresponding
21c90 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 octet. If this p
21ca0 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 rocess generates
21cb0 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d an invalid UTF-
21cc0 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 8 encoding,.** t
21cd0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
21ce0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
21cf0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f <b>Note to Windo
21d00 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 ws users:</b> T
21d10 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 he encoding used
21d20 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d for the filenam
21d30 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 e argument.** of
21d40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
21d50 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e and sqlite3_open
21d60 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 _v2() must be UT
21d70 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 F-8, not whateve
21d80 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 r.** codepage is
21d90 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
21da0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 ed. Filenames c
21db0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e ontaining intern
21dc0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 ational.** chara
21dd0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f cters must be co
21de0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 nverted to UTF-8
21df0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e prior to passin
21e00 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 g them into.** s
21e10 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 qlite3_open() or
21e20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
21e30 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ()..**.** <b>Not
21e40 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e e to Windows Run
21e50 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 time users:</b>
21e60 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 The temporary d
21e70 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 irectory must be
21e80 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f set.** prior to
21e90 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 calling sqlite3
21ea0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 _open() or sqlit
21eb0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f e3_open_v2(). O
21ec0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 therwise, variou
21ed0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 s.** features th
21ee0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 at require the u
21ef0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 se of temporary
21f00 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a files may fail..
21f10 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
21f20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 [sqlite3_temp_di
21f30 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 rectory].*/.int
21f40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
21f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
21f60 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
21f70 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
21f80 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
21f90 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
21fa0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
21fb0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
21fc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
21fd0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 n16(. const voi
21fe0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f d *filename, /
21ff0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e * Database filen
22000 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a ame (UTF-16) */.
22010 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
22020 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
22030 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
22040 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c le */.);.int sql
22050 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 ite3_open_v2(.
22060 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
22070 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
22080 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
22090 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
220a0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 3 **ppDb,
220b0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
220c0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 db handle */.
220d0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 int flags,
220e0 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 /* Flags
220f0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
22100 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a *zVfs /*
22110 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 Name of VFS mod
22120 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b ule to use */.);
22130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
22140 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 : Obtain Values
22150 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 For URI Paramete
22160 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 rs.**.** These a
22170 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 re utility routi
22180 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 nes, useful to V
22190 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
221a0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a ns, that check.*
221b0 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 * to see if a da
221c0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 tabase file was
221d0 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 a URI that conta
221e0 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 ined a specific
221f0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 query .** parame
22200 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f ter, and if so o
22210 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 btains the value
22220 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 of that query p
22230 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
22240 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 If F is the data
22250 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f base filename po
22260 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 inter passed int
22270 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 o the xOpen() me
22280 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 thod of .** a VF
22290 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
222a0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 when the flags
222b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
222c0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 en() has one or
222d0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 .** more of the
222e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
222f0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ] or [SQLITE_OPE
22300 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 N_MAIN_DB] bits
22310 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 set and.** P is
22320 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
22330 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c query parameter,
22340 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
22350 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
22360 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 ,P) returns the
22370 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a value of the P.*
22380 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 * parameter if i
22390 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 t exists or a NU
223a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 LL pointer if P
223b0 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 does not appear
223c0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 as a .** query p
223d0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 arameter on F.
223e0 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 If P is a query
223f0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a parameter of F.*
22400 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 * has no explici
22410 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 t value, then sq
22420 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
22430 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 ter(F,P) returns
22440 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
22450 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
22460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
22470 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
22480 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 F,P,B) routine a
22490 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 ssumes that P is
224a0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 a boolean.** pa
224b0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 rameter and retu
224c0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 rns true (1) or
224d0 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 false (0) accord
224e0 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 ing to the value
224f0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 .** of P. The s
22500 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
22510 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e an(F,P,B) routin
22520 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
22530 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 1) if the.** val
22540 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 ue of query para
22550 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f meter P is one o
22560 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c f "yes", "true",
22570 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a or "on" in any.
22580 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 ** case or if th
22590 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
225a0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e ith a non-zero n
225b0 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 umber. The .**
225c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
225d0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
225e0 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 nes returns fals
225f0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c e (0) if the val
22600 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 ue of.** query p
22610 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e arameter P is on
22620 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 e of "no", "fals
22630 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 e", or "off" in
22640 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 any case or.** i
22650 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 f the value begi
22660 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 ns with a numeri
22670 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 c zero. If P is
22680 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 not a query.**
22690 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f parameter on F o
226a0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f r if the value o
226b0 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 f P is does not
226c0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 match any of the
226d0 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 .** above, then
226e0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
226f0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 ean(F,P,B) retur
22700 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a ns (B!=0)..**.**
22710 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
22720 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f _int64(F,P,D) ro
22730 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 utine converts t
22740 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e he value of P in
22750 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 to a.** 64-bit s
22760 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
22770 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 d returns that i
22780 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 nteger, or D if
22790 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 P does not.** ex
227a0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c ist. If the val
227b0 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 ue of P is somet
227c0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 hing other than
227d0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e an integer, then
227e0 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 .** zero is retu
227f0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 rned..** .** If
22800 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e F is a NULL poin
22810 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ter, then sqlite
22820 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
22830 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c F,P) returns NUL
22840 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 L and.** sqlite3
22850 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
22860 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 ,B) returns B.
22870 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 If F is not a NU
22880 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a LL pointer and.*
22890 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 * is not a datab
228a0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d ase file pathnam
228b0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 e pointer that S
228c0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 QLite passed int
228d0 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 o the xOpen.** V
228e0 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 FS method, then
228f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
22900 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
22910 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 undefined and pr
22920 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 obably.** undesi
22930 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 rable..*/.const
22940 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 char *sqlite3_ur
22950 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 i_parameter(cons
22960 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d t char *zFilenam
22970 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
22980 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 Param);.int sqli
22990 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
229a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
229b0 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a e, const char *z
229c0 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 Param, int bDefa
229d0 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e ult);.sqlite3_in
229e0 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f t64 sqlite3_uri_
229f0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 int64(const char
22a00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 *, const char*,
22a10 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a sqlite3_int64);.
22a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
22a30 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e : Error Codes An
22a40 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a d Messages.**.**
22a50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
22a60 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 rcode() interfac
22a70 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
22a80 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
22a90 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
22aa0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
22ab0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 for the most re
22ac0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 cent failed sqli
22ad0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a te3_* API call.*
22ae0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
22af0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f h a [database co
22b00 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 nnection]. If a
22b10 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 prior API call f
22b20 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 ailed.** but the
22b30 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 most recent API
22b40 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c call succeeded,
22b50 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
22b60 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 e from.** sqlite
22b70 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 3_errcode() is u
22b80 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 ndefined. ^The
22b90 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
22ba0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e _errcode().** in
22bb0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73 terface is the s
22bc0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20 ame except that
22bd0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e it always return
22be0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e s the .** [exten
22bf0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
22c00 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e even when exten
22c10 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
22c20 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 are.** disabled
22c30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
22c40 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e ite3_errmsg() an
22c50 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 d sqlite3_errmsg
22c60 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 16() return Engl
22c70 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 ish-language.**
22c80 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69 text that descri
22c90 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 bes the error, a
22ca0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
22cb0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 r UTF-16 respect
22cc0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f ively..** ^(Memo
22cd0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
22ce0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
22cf0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
22d00 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 nternally..** Th
22d10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
22d20 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 es not need to w
22d30 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 orry about freei
22d40 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a ng the result..*
22d50 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 * However, the e
22d60 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 rror string migh
22d70 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e t be overwritten
22d80 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 or deallocated
22d90 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 by.** subsequent
22da0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 calls to other
22db0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
22dc0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a functions.)^.**
22dd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
22de0 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 _errstr() interf
22df0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
22e00 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 English-language
22e10 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 text.** that de
22e20 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 scribes the [res
22e30 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 ult code], as UT
22e40 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 F-8..** ^(Memory
22e50 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
22e60 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
22e70 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
22e80 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d ernally.** and m
22e90 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 ust not be freed
22ea0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
22eb0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ion)^..**.** Whe
22ec0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
22ed0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
22ee0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 ] is in use, it
22ef0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 might be the.**
22f00 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f case that a seco
22f10 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 nd error occurs
22f20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68 on a separate th
22f30 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a read in between.
22f40 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 ** the time of t
22f50 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 he first error a
22f60 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 nd the call to t
22f70 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e hese interfaces.
22f80 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 .** When that ha
22f90 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e ppens, the secon
22fa0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 d error will be
22fb0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 reported since t
22fc0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 hese.** interfac
22fd0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 es always report
22fe0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
22ff0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f result. To avo
23000 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 id.** this, each
23010 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 thread can obta
23020 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 in exclusive use
23030 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
23040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a e connection] D.
23050 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b ** by invoking [
23060 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e sqlite3_mutex_en
23070 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 ter]([sqlite3_db
23080 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f _mutex](D)) befo
23090 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 re beginning.**
230a0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 to use D and inv
230b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
230c0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c utex_leave]([sql
230d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
230e0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 )) after.** all
230f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 calls to the int
23100 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 erfaces listed h
23110 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 ere are complete
23120 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 d..**.** If an i
23130 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 nterface fails w
23140 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ith SQLITE_MISUS
23150 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 E, that means th
23160 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 e interface.** w
23170 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 as invoked incor
23180 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 rectly by the ap
23190 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 plication. In t
231a0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a hat case, the.**
231b0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 error code and
231c0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d message may or m
231d0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a ay not be set..*
231e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 /.int sqlite3_er
231f0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 rcode(sqlite3 *d
23200 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f b);.int sqlite3_
23210 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
23220 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 (sqlite3 *db);.c
23230 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
23240 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 e3_errmsg(sqlite
23250 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 3*);.const void
23260 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 *sqlite3_errmsg1
23270 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 6(sqlite3*);.con
23280 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
23290 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f _errstr(int);../
232a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
232b0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a QL Statement Obj
232c0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ect.** KEYWORDS:
232d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 {prepared state
232e0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 ment} {prepared
232f0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a statements}.**.*
23300 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
23310 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 this object rep
23320 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 resents a single
23330 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a SQL statement..
23340 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
23350 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 s variously know
23360 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 n as a "prepared
23370 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 statement" or a
23380 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 .** "compiled SQ
23390 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 L statement" or
233a0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 simply as a "sta
233b0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 tement"..**.** T
233c0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 he life of a sta
233d0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f tement object go
233e0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b es something lik
233f0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f e this:.**.** <o
23400 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 l>.** <li> Creat
23410 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 e the object usi
23420 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
23430 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 are_v2()] or a r
23440 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 elated.** f
23450 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e unction..** <li>
23460 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 Bind values to
23470 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 [host parameters
23480 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 ] using the sqli
23490 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 te3_bind_*().**
234a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e interfaces.
234b0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 .** <li> Run the
234c0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 SQL by calling
234d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
234e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
234f0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 es..** <li> Rese
23500 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
23510 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
23520 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
23530 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
23540 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
23550 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
23560 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
23570 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
23580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
23590 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
235a0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 /ol>.**.** Refer
235b0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f to documentatio
235c0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
235d0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f methods above fo
235e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 r additional.**
235f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
23600 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
23610 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 qlite3_stmt sqli
23620 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a te3_stmt;../*.**
23630 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 CAPI3REF: Run-t
23640 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a ime Limits.**.**
23650 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 ^(This interfac
23660 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
23670 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
23680 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
23690 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
236a0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
236b0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
236c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
236d0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
236e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
236f0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
23700 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
23710 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
23720 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
23730 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
23740 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
23750 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
23760 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
23770 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
23780 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
23790 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
237a0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
237b0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
237c0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 struct.)^.**.**
237d0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 ^If the new limi
237e0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
237f0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
23800 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
23810 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 ** ^(For each li
23820 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c mit category SQL
23830 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d ITE_LIMIT_<i>NAM
23840 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 E</i> there is a
23850 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 .** [limits | h
23860 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d ard upper bound]
23870 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 .** set at compi
23880 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 le-time by a C p
23890 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
238a0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d o called.** [lim
238b0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 its | SQLITE_MAX
238c0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a _<i>NAME</i>]..*
238d0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
238e0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
238f0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
23900 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d _".))^.** ^Attem
23910 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 pts to increase
23920 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 a limit above it
23930 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 s hard upper bou
23940 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 nd are.** silent
23950 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 ly truncated to
23960 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 the hard upper b
23970 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 ound..**.** ^Reg
23980 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
23990 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 er or not the li
239a0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c mit was changed,
239b0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
239c0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 3_limit()] inter
239d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
239e0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
239f0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 the limit..** ^H
23a00 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 ence, to find th
23a10 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
23a20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f of a limit witho
23a30 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a ut changing it,.
23a40 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 ** simply invoke
23a50 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
23a60 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 with the third p
23a70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 arameter set to
23a80 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 -1..**.** Run-ti
23a90 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
23aa0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
23ab0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
23ac0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
23ad0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
23ae0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
23af0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
23b00 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
23b10 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
23b20 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
23b30 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
23b40 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
23b50 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
23b60 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 b browser that h
23b70 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 as its own datab
23b80 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 ases for storing
23b90 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 history and.**
23ba0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 separate databas
23bb0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 es controlled by
23bc0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c JavaScript appl
23bd0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 ications downloa
23be0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 ded.** off the I
23bf0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e nternet. The in
23c00 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 ternal databases
23c10 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 can be given th
23c20 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 e.** large, defa
23c30 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 ult limits. Dat
23c40 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 abases managed b
23c50 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 y external sourc
23c60 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 es can.** be giv
23c70 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 en much smaller
23c80 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 limits designed
23c90 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e to prevent a den
23ca0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a ial of service.*
23cb0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c * attack. Devel
23cc0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f opers might also
23cd0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 want to use the
23ce0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
23cf0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 thorizer()].** i
23d00 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 nterface to furt
23d10 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 her control untr
23d20 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 usted SQL. The
23d30 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
23d40 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 base.** created
23d50 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 by an untrusted
23d60 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f script can be co
23d70 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ntained using th
23d80 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 e.** [max_page_c
23d90 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a ount] [PRAGMA]..
23da0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 **.** New run-ti
23db0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 me limit categor
23dc0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ies may be added
23dd0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
23de0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ses..*/.int sqli
23df0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 te3_limit(sqlite
23e00 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 3*, int id, int
23e10 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 newVal);../*.**
23e20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
23e30 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 me Limit Categor
23e40 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ies.** KEYWORDS:
23e50 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 {limit category
23e60 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f } {*limit catego
23e70 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ries}.**.** Thes
23e80 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 e constants defi
23e90 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f ne various perfo
23ea0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a rmance limits.**
23eb0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 that can be low
23ec0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 ered at run-time
23ed0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
23ee0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 limit()]..** The
23ef0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 synopsis of the
23f00 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 meanings of the
23f10 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 various limits
23f20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a is shown below..
23f30 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** Additional in
23f40 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 formation is ava
23f50 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 ilable at [limit
23f60 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 s | Limits in SQ
23f70 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c Lite]..**.** <dl
23f80 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 >.** [[SQLITE_LI
23f90 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c MIT_LENGTH]] ^(<
23fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
23fb0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c LENGTH</dt>.** <
23fc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 dd>The maximum s
23fd0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e ize of any strin
23fe0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 g or BLOB or tab
23ff0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 le row, in bytes
24000 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b .<dd>)^.**.** [[
24010 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
24020 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e _LENGTH]] ^(<dt>
24030 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c SQLITE_LIMIT_SQL
24040 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
24050 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
24060 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c length of an SQL
24070 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 statement, in b
24080 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ytes.</dd>)^.**.
24090 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
240a0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 T_COLUMN]] ^(<dt
240b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
240c0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LUMN</dt>.** <dd
240d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
240e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
240f0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 n a table defini
24100 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a tion or in the.*
24110 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 * result set of
24120 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 a [SELECT] or th
24130 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
24140 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 of columns in a
24150 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e n index.** or in
24160 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 an ORDER BY or
24170 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e GROUP BY clause.
24180 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
24190 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
241a0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e R_DEPTH]] ^(<dt>
241b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
241c0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 R_DEPTH</dt>.**
241d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
241e0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 depth of the par
241f0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 se tree on any e
24200 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 xpression.</dd>)
24210 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
24220 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
24230 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 SELECT]] ^(<dt>S
24240 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
24250 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e OUND_SELECT</dt>
24260 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
24270 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 mum number of te
24280 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e rms in a compoun
24290 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 d SELECT stateme
242a0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a nt.</dd>)^.**.**
242b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
242c0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e VDBE_OP]] ^(<dt>
242d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
242e0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 E_OP</dt>.** <dd
242f0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
24300 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 ber of instructi
24310 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c ons in a virtual
24320 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d machine program
24330 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c .** used to impl
24340 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 ement an SQL sta
24350 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 tement. This li
24360 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 mit is not curre
24370 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 ntly.** enforced
24380 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 , though that mi
24390 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 ght be added in
243a0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 some future rele
243b0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 ase of.** SQLite
243c0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
243d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 [SQLITE_LIMIT_FU
243e0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c NCTION_ARG]] ^(<
243f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
24400 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 FUNCTION_ARG</dt
24410 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
24420 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
24430 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 rguments on a fu
24440 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a nction.</dd>)^.*
24450 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
24460 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e MIT_ATTACHED]] ^
24470 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
24480 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a T_ATTACHED</dt>.
24490 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
244a0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 um number of [AT
244b0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 TACH | attached
244c0 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 databases].)^</d
244d0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
244e0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 E_LIMIT_LIKE_PAT
244f0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a TERN_LENGTH]].**
24500 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
24510 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
24520 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
24530 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
24540 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 length of the pa
24550 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 ttern argument t
24560 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a o the [LIKE] or.
24570 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 ** [GLOB] operat
24580 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ors.</dd>)^.**.*
24590 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
245a0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
245b0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 ]].** ^(<dt>SQLI
245c0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
245d0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a E_NUMBER</dt>.**
245e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
245f0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 index number of
24600 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d any [parameter]
24610 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 in an SQL state
24620 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b ment.)^.**.** [[
24630 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
24640 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c GGER_DEPTH]] ^(<
24650 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
24660 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 TRIGGER_DEPTH</d
24670 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
24680 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 ximum depth of r
24690 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 ecursion for tri
246a0 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ggers.</dd>)^.**
246b0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
246c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
246d0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
246e0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
246f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
24700 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 SQL_LENGTH
24710 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
24720 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
24730 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 _COLUMN
24740 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 2.#de
24750 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
24760 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 T_EXPR_DEPTH
24770 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
24780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
24790 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
247a0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 CT 4.#
247b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
247c0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 MIT_VDBE_OP
247d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
247e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
247f0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
24800 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 G 6
24810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24820 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 LIMIT_ATTACHED
24830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24840 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
24850 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
24860 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 ERN_LENGTH
24870 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
24880 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
24890 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 _NUMBER
248a0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
248b0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
248c0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
248d0 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 10../*.** CAPI
248e0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 3REF: Compiling
248f0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
24900 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
24910 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
24920 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 piler}.**.** To
24930 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 execute an SQL q
24940 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 uery, it must fi
24950 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
24960 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
24970 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
24980 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
24990 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
249a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
249b0 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 t, "db", is a [d
249c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
249d0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f on] obtained fro
249e0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 m a.** prior suc
249f0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
24a00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
24a10 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
24a20 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c v2()] or.** [sql
24a30 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 ite3_open16()].
24a40 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f The database co
24a50 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f nnection must no
24a60 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 t have been clos
24a70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ed..**.** The se
24a80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 cond argument, "
24a90 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 zSql", is the st
24aa0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
24ab0 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a mpiled, encoded.
24ac0 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ** as either UTF
24ad0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 -8 or UTF-16. T
24ae0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
24af0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 re() and sqlite3
24b00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a _prepare_v2().**
24b10 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 interfaces use
24b20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 UTF-8, and sqlit
24b30 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 e3_prepare16() a
24b40 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
24b50 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 re16_v2().** use
24b60 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e UTF-16..**.** ^
24b70 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 If the nByte arg
24b80 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 ument is less th
24b90 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 an zero, then zS
24ba0 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f ql is read up to
24bb0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 the.** first ze
24bc0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e ro terminator. ^
24bd0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d If nByte is non-
24be0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 negative, then i
24bf0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d t is the maximum
24c00 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 .** number of b
24c10 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a ytes read from z
24c20 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 Sql. ^When nByt
24c30 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 e is non-negativ
24c40 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 e, the.** zSql s
24c50 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 tring ends at ei
24c60 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 ther the first '
24c70 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 \000' or '\u0000
24c80 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a ' character or.*
24c90 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 * the nByte-th b
24ca0 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 yte, whichever c
24cb0 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 omes first. If t
24cc0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a he caller knows.
24cd0 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 ** that the supp
24ce0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e lied string is n
24cf0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 ul-terminated, t
24d00 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 hen there is a s
24d10 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 mall.** performa
24d20 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f nce advantage to
24d30 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 be gained by pa
24d40 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 ssing an nByte p
24d50 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a arameter that.**
24d60 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 is equal to the
24d70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
24d80 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 in the input st
24d90 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e ring <i>includin
24da0 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c g</i>.** the nul
24db0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 -terminator byte
24dc0 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20 s as this saves
24dd0 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 SQLite from havi
24de0 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 ng to.** make a
24df0 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 copy of the inpu
24e00 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 t string..**.**
24e10 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f ^If pzTail is no
24e20 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 t NULL then *pzT
24e30 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 ail is made to p
24e40 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 oint to the firs
24e50 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 t byte.** past t
24e60 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 he end of the fi
24e70 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e rst SQL statemen
24e80 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 t in zSql. Thes
24e90 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a e routines only.
24ea0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 ** compile the f
24eb0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 irst statement i
24ec0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 n zSql, so *pzTa
24ed0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 il is left point
24ee0 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 ing to.** what r
24ef0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 emains uncompile
24f00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d d..**.** ^*ppStm
24f10 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 t is left pointi
24f20 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 ng to a compiled
24f30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
24f40 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 ment] that can b
24f50 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 e.** executed us
24f60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
24f70 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 p()]. ^If there
24f80 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 is an error, *p
24f90 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 pStmt is set.**
24fa0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 to NULL. ^If th
24fb0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e e input text con
24fc0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 tains no SQL (if
24fd0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e the input is an
24fe0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 empty.** string
24ff0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 or a comment) t
25000 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 hen *ppStmt is s
25010 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 et to NULL..** T
25020 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 he calling proce
25030 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 dure is responsi
25040 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 ble for deleting
25050 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a the compiled.**
25060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 SQL statement u
25070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
25080 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 nalize()] after
25090 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 it has finished
250a0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 with it..** ppSt
250b0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 mt may not be NU
250c0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 LL..**.** ^On su
250d0 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 ccess, the sqlit
250e0 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d e3_prepare() fam
250f0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 ily of routines
25100 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
25110 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 K];.** otherwise
25120 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d an [error code]
25130 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
25140 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
25150 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 prepare_v2() and
25160 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
25170 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 16_v2() interfac
25180 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d es are.** recomm
25190 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 ended for all ne
251a0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 w programs. The
251b0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 two older interf
251c0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 aces are retaine
251d0 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 d.** for backwar
251e0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
251f0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 , but their use
25200 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a is discouraged..
25210 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 ** ^In the "v2"
25220 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 interfaces, the
25230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25240 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 nt.** that is re
25250 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c turned (the [sql
25260 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 ite3_stmt] objec
25270 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f t) contains a co
25280 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 py of the.** ori
25290 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 ginal SQL text.
252a0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 This causes the
252b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
252c0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a interface to.**
252d0 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e behave differen
252e0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 tly in three way
252f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a s:.**.** <ol>.**
25300 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 <li>.** ^If the
25310 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
25320 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 changes, instea
25330 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b d of returning [
25340 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 SQLITE_SCHEMA] a
25350 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 s it.** always u
25360 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 sed to do, [sqli
25370 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
25380 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
25390 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c ecompile the SQL
253a0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e .** statement an
253b0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 d try to run it
253c0 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a again..** </li>.
253d0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 **.** <li>.** ^W
253e0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 hen an error occ
253f0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 urs, [sqlite3_st
25400 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ep()] will retur
25410 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 n one of the det
25420 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 ailed.** [error
25430 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e codes] or [exten
25440 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d ded error codes]
25450 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 . ^The legacy b
25460 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 ehavior was that
25470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
25480 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 p()] would only
25490 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 return a generic
254a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
254b0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 result code.** a
254c0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
254d0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f on would have to
254e0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 make a second c
254f0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
25500 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f reset()].** in o
25510 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 rder to find the
25520 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 underlying caus
25530 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d e of the problem
25540 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 . With the "v2"
25550 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 prepare.** inter
25560 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 faces, the under
25570 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 lying reason for
25580 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 the error is re
25590 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
255a0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a ly..** </li>.**.
255b0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
255c0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 he specific valu
255d0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 e bound to [para
255e0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 meter | host par
255f0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a ameter] in the .
25600 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 ** WHERE clause
25610 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 might influence
25620 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 the choice of qu
25630 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 ery plan for a s
25640 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 tatement,.** the
25650 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
25660 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 will be automati
25670 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 cally recompiled
25680 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 , as if there ha
25690 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 d been .** a sch
256a0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 ema change, on t
256b0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 he first [sqlit
256c0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
256d0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 following any ch
256e0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ange.** to the [
256f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
25700 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 t | bindings] of
25710 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 that [parameter
25720 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 ]. .** ^The spec
25730 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 ific value of WH
25740 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 ERE-clause [para
25750 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 meter] might inf
25760 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 luence the .** c
25770 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 hoice of query p
25780 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d lan if the param
25790 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 eter is the left
257a0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 -hand side of a
257b0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c [LIKE].** or [GL
257c0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 OB] operator or
257d0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
257e0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 is compared to
257f0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d an indexed colum
25800 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 n.** and the [SQ
25810 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 LITE_ENABLE_STAT
25820 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 3] compile-time
25830 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 option is enable
25840 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f d..** the .** </
25850 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a li>.** </ol>.*/.
25860 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
25870 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a are(. sqlite3 *
25880 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
25890 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
258a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
258b0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
258c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
258d0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
258e0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
258f0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
25900 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
25910 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
25920 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
25930 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
25940 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
25950 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
25960 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
25970 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
25980 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
25990 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
259a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
259b0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
259c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
259d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
259e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
259f0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
25a00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
25a10 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
25a20 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
25a30 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
25a40 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
25a50 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
25a60 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
25a70 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
25a80 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
25a90 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
25aa0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
25ab0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
25ac0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
25ad0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
25ae0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
25af0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a ite3_prepare16(.
25b00 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
25b10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
25b20 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
25b30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 const void *zS
25b40 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
25b50 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
25b60 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 16 encoded */.
25b70 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 int nByte,
25b80 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
25b90 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 um length of zSq
25ba0 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 l in bytes. */.
25bb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a sqlite3_stmt **
25bc0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a ppStmt, /* OUT:
25bd0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c Statement handl
25be0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
25bf0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f d **pzTail /
25c00 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 * OUT: Pointer t
25c10 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e o unused portion
25c20 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 of zSql */.);.i
25c30 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
25c40 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
25c50 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
25c60 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
25c70 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
25c80 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
25c90 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
25ca0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
25cb0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
25cc0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
25cd0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
25ce0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
25cf0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
25d00 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
25d10 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
25d20 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
25d30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
25d40 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
25d50 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
25d60 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
25d70 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
25d80 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
25d90 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
25da0 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e L.**.** ^This in
25db0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
25dc0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
25dd0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 a saved copy of
25de0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 the original.**
25df0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f SQL text used to
25e00 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 create a [prepa
25e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
25e20 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
25e30 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 was.** compiled
25e40 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
25e50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
25e60 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
25e70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
25e80 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 ..*/.const char
25e90 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c *sqlite3_sql(sql
25ea0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
25eb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
25ec0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
25ed0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
25ee0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 t Writes The Dat
25ef0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 abase.**.** ^The
25f00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
25f10 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 adonly(X) interf
25f20 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
25f30 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a (non-zero) if.*
25f40 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 * and only if th
25f50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
25f60 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e ement] X makes n
25f70 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 o direct changes
25f80 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 to.** the conte
25f90 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
25fa0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e se file..**.** N
25fb0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 ote that [applic
25fc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
25fd0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a L functions] or.
25fe0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
25ff0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 es] might change
26000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e the database in
26010 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 directly as a si
26020 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 de effect. .**
26030 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 ^(For example, i
26040 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
26050 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 defines a funct
26060 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 ion "eval()" tha
26070 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c t .** calls [sql
26080 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 ite3_exec()], th
26090 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 en the following
260a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
260b0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ould.** change t
260c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
260d0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 through side-ef
260e0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c fects:.**.** <bl
260f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
26100 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c * SELECT eval
26110 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 ('DELETE FROM t1
26120 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c ') FROM t2;.** <
26130 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
26140 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 e>.**.** But bec
26150 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 ause the [SELECT
26160 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 ] statement does
26170 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
26180 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a database file.**
26190 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 directly, sqlit
261a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
261b0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 () would still r
261c0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a eturn true.)^.**
261d0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e .** ^Transaction
261e0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 control stateme
261f0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 nts such as [BEG
26200 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b IN], [COMMIT], [
26210 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 ROLLBACK],.** [S
26220 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b AVEPOINT], and [
26230 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 RELEASE] cause s
26240 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
26250 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
26260 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 true,.** since
26270 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 the statements t
26280 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 hemselves do not
26290 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 actually modify
262a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 the database bu
262b0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 t.** rather they
262c0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d control the tim
262d0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 ing of when othe
262e0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 r statements mod
262f0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 ify the .** data
26300 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 base. ^The [ATT
26310 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 ACH] and [DETACH
26320 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 ] statements als
26330 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 o cause.** sqlit
26340 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
26350 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
26360 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 e since, while t
26370 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a hose statements.
26380 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f ** change the co
26390 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 nfiguration of a
263a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
263b0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f tion, they do no
263c0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 t make .** chang
263d0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e es to the conten
263e0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
263f0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e e files on disk.
26400 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
26410 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 stmt_readonly(sq
26420 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
26430 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
26440 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
26450 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 f A Prepared Sta
26460 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 tement Has Been
26470 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 Reset.**.** ^The
26480 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
26490 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 sy(S) interface
264a0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f returns true (no
264b0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a n-zero) if the.*
264c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
264d0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 ement] S has bee
264e0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 n stepped at lea
264f0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a st once using .*
26500 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
26510 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 S)] but has not
26520 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f run to completio
26530 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 n and/or has not
26540 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 .** been reset
26550 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
26560 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 eset(S)]. ^The
26570 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
26580 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y(S).** interfac
26590 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 e returns false
265a0 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 if S is a NULL p
265b0 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 ointer. If S is
265c0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 not a .** NULL
265d0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e pointer and is n
265e0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ot a pointer to
265f0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 a valid [prepare
26600 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
26610 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 object, then the
26620 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
26630 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
26640 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e bly undesirable.
26650 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
26660 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
26670 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e d in combination
26680 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
26690 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 tmt()].** to loc
266a0 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 ate all prepared
266b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f statements asso
266c0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 ciated with a da
266d0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 tabase .** conne
266e0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 ction that are i
266f0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 n need of being
26700 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e reset. This can
26710 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 be used,.** for
26720 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 example, in dia
26730 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 gnostic routines
26740 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 to search for p
26750 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 repared .** stat
26760 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 ements that are
26770 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 holding a transa
26780 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 ction open..*/.i
26790 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
267a0 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d busy(sqlite3_stm
267b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
267c0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
267d0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
267e0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
267f0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c : {protected sql
26800 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 ite3_value} {unp
26810 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
26820 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 _value}.**.** SQ
26830 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 Lite uses the sq
26840 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
26850 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 ct to represent
26860 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 all values.** th
26870 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 at can be stored
26880 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 in a database t
26890 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 able. SQLite use
268a0 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 s dynamic typing
268b0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 .** for the valu
268c0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e es it stores. ^
268d0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
268e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
268f0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
26900 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
26910 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
26920 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
26930 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
26940 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
26950 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
26960 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
26970 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
26980 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
26990 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
269a0 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
269b0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
269c0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
269d0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
269e0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
269f0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
26a00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
26a10 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
26a20 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
26a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
26a40 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
26a50 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
26a60 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
26a70 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
26a80 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
26a90 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
26aa0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
26ab0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
26ac0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
26ad0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
26ae0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 eld. An interna
26af0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 l mutex is held
26b00 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a for a protected.
26b10 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
26b20 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d object but no m
26b30 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
26b40 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a an unprotected.
26b50 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
26b60 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c object. If SQL
26b70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
26b80 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 to be single-thr
26b90 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b eaded.** (with [
26ba0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
26bb0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 E=0] and with [s
26bc0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
26bd0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 e()] returning 0
26be0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 ).** or if SQLit
26bf0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 e is run in one
26c00 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 of reduced mutex
26c10 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 modes .** [SQLI
26c20 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
26c30 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
26c40 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
26c50 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 HREAD].** then t
26c60 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 here is no disti
26c70 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
26c80 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
26c90 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
26ca0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
26cb0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 s and they can b
26cc0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e e used interchan
26cd0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 geably. However
26ce0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d ,.** for maximum
26cf0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 code portabilit
26d00 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e y it is recommen
26d10 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
26d20 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d tions.** still m
26d30 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
26d40 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
26d50 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
26d60 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
26d70 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 _value objects e
26d80 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 ven when not str
26d90 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a ictly required..
26da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
26db0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
26dc0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
26dd0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
26de0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
26df0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
26e00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
26e10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
26e20 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
26e30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
26e40 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 value object ret
26e50 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
26e60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
26e70 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 e()] is unprotec
26e80 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 ted..** Unprotec
26e90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
26ea0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e e objects may on
26eb0 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a ly be used with.
26ec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ** [sqlite3_resu
26ed0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 lt_value()] and
26ee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
26ef0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b lue()]..** The [
26f00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
26f10 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c ob | sqlite3_val
26f20 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c ue_type()] famil
26f30 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y of.** interfac
26f40 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 es require prote
26f50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
26f60 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 ue objects..*/.t
26f70 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 ypedef struct Me
26f80 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b m sqlite3_value;
26f90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
26fa0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 : SQL Function C
26fb0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a ontext Object.**
26fc0 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 .** The context
26fd0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 in which an SQL
26fe0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 function execute
26ff0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 s is stored in a
27000 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e n.** sqlite3_con
27010 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 text object. ^A
27020 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
27030 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
27040 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
27050 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
27060 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
27070 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
27080 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
27090 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
270a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
270b0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
270c0 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
270d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
270e0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
270f0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
27100 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
27110 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
27120 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
27130 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
27140 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
27150 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
27160 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
27170 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
27180 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
27190 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
271a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
271b0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
271c0 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
271d0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
271e0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
271f0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
27200 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
27210 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b Statements.** K
27220 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 EYWORDS: {host p
27230 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 arameter} {host
27240 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 parameters} {hos
27250 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
27260 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
27270 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b SQL parameter} {
27280 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 SQL parameters}
27290 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 {parameter bindi
272a0 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ng}.**.** ^(In t
272b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
272c0 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b text input to [
272d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
272e0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 v2()] and its va
272f0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 riants,.** liter
27300 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 als may be repla
27310 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 ced by a [parame
27320 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 ter] that matche
27330 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 s one of followi
27340 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a ng.** templates:
27350 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
27360 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 li> ?.** <li>
27370 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 ?NNN.** <li> :V
27380 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 VV.** <li> @VVV
27390 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a .** <li> $VVV.*
273a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
273b0 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 the templates a
273c0 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 bove, NNN repres
273d0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 ents an integer
273e0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 literal,.** and
273f0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 VVV represents a
27400 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 n alphanumeric i
27410 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 dentifier.)^ ^T
27420 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 he values of the
27430 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 se.** parameters
27440 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 (also called "h
27450 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
27460 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 mes" or "SQL par
27470 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e ameters").** can
27480 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 be set using th
27490 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
274a0 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 () routines defi
274b0 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ned here..**.**
274c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
274d0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ent to the sqlit
274e0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 e3_bind_*() rout
274f0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a ines is always.*
27500 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 * a pointer to t
27510 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 he [sqlite3_stmt
27520 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
27530 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 d from.** [sqlit
27540 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
27550 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
27560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 ..**.** ^The sec
27570 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
27580 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
27590 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 SQL parameter t
275a0 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 o be set..** ^Th
275b0 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 e leftmost SQL p
275c0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
275d0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 index of 1. ^Wh
275e0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 en the same name
275f0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 d.** SQL paramet
27600 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 er is used more
27610 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e than once, secon
27620 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 d and subsequent
27630 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 .** occurrences
27640 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e have the same in
27650 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 dex as the first
27660 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 occurrence..**
27670 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e ^The index for n
27680 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 amed parameters
27690 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 can be looked up
276a0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
276b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
276c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 meter_index()] A
276d0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 PI if desired.
276e0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f ^The index.** fo
276f0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 r "?NNN" paramet
27700 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 ers is the value
27710 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 of NNN..** ^The
27720 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 NNN value must
27730 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 be between 1 and
27740 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 the [sqlite3_li
27750 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 mit()].** parame
27760 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ter [SQLITE_LIMI
27770 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
27780 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 R] (default valu
27790 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e e: 999)..**.** ^
277a0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
277b0 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 nt is the value
277c0 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 to bind to the p
277d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 arameter..**.**
277e0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
277f0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
27800 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
27810 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
27820 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
27830 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
27840 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
27850 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
27860 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
27870 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
27880 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
27890 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
278a0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
278b0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
278c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
278d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
278e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
278f0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 _text16().** is
27900 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
27910 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
27920 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
27930 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
27940 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
27950 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
27960 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 r..** If the fou
27970 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
27980 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
27990 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 ob() is negative
279a0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 , then.** the be
279b0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
279c0 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e ned..** If a non
279d0 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 -negative fourth
279e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
279f0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 ovided to sqlite
27a00 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 3_bind_text().**
27a10 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
27a20 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 _text16() then t
27a30 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 hat parameter mu
27a40 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
27a50 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 ffset.** where t
27a60 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
27a70 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 r would occur as
27a80 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e suming the strin
27a90 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 g were NUL.** te
27aa0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
27ab0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
27ac0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f occur at byte o
27ad0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e ffsets less than
27ae0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f .** the value o
27af0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
27b00 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 ameter then the
27b10 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
27b20 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 value will.** c
27b30 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
27b40 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c NULs. The resul
27b50 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
27b60 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e involving strin
27b70 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 gs.** with embed
27b80 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
27b90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
27ba0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
27bb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
27bc0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
27bd0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e _bind_text(), an
27be0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e d.** sqlite3_bin
27bf0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 d_text16() is a
27c00 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
27c10 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
27c20 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
27c30 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
27c40 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
27c50 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
27c60 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
27c70 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
27c80 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
27c90 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
27ca0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
27cb0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 3_bind_blob(),.*
27cc0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
27cd0 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 ext(), or sqlite
27ce0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
27cf0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 fails. .** ^If
27d00 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
27d10 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
27d20 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
27d30 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
27d40 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
27d50 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
27d60 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
27d70 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
27d80 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
27d90 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
27da0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
27db0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
27dc0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
27dd0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
27de0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
27df0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
27e00 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
27e10 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
27e20 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
27e30 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
27e40 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
27e50 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
27e60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
27e70 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
27e80 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
27e90 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
27ea0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
27eb0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
27ec0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
27ed0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
27ee0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
27ef0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
27f00 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
27f10 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
27f20 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
27f30 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
27f40 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
27f50 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
27f60 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
27f70 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
27f80 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
27f90 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
27fa0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
27fb0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
27fc0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
27fd0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
27fe0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
27ff0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
28000 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 BLOB..**.** ^If
28010 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
28020 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
28030 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
28040 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
28050 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
28060 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28070 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
28080 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
28090 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
280a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
280b0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
280c0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
280d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
280e0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
280f0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
28100 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
28110 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
28120 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
28130 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
28140 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
28150 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
28160 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
28170 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
28180 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
28190 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
281a0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
281b0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
281c0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
281d0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
281e0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
281f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
28200 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
28210 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
28220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
28230 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
28240 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
28250 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
28260 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
28270 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
28280 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 g..** ^[SQLITE_R
28290 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
282a0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
282b0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
282c0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
282d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
282e0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
282f0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
28300 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
28310 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
28320 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
28330 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
28340 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
28350 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
28360 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
28370 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
28380 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
28390 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
283a0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
283b0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
283c0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
283d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
283e0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
283f0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
28400 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
28410 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
28420 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 t*, int, int);.i
28430 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
28440 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
28450 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 mt*, int, sqlite
28460 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 3_int64);.int sq
28470 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 lite3_bind_null(
28480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
28490 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
284a0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
284b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
284c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 onst char*, int
284d0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
284e0 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
284f0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
28500 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
28510 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
28520 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
28530 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
28540 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
28550 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
28560 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
28570 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
28580 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
28590 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
285a0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
285b0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
285c0 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
285d0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ters.**.** ^This
285e0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
285f0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
28600 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
28610 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
28620 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
28630 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
28640 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
28650 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
28660 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
28670 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
28680 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
28690 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
286a0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
286b0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
286c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
286d0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
286e0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
286f0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
28700 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
28710 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
28720 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
28730 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
28740 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
28750 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
28760 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
28770 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
28780 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
28790 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
287a0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
287b0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
287c0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
287d0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
287e0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
287f0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
28800 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
28810 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
28820 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
28830 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
28840 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
28850 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
28860 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
28870 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
28880 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
28890 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
288a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
288b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
288c0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
288d0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a t Parameter.**.*
288e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
288f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
28900 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(P,N) interfac
28910 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 e returns.** the
28920 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 name of the N-t
28930 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 h [SQL parameter
28940 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 ] in the [prepar
28950 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
28960 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 .** ^(SQL parame
28970 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
28980 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
28990 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
289a0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
289b0 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
289c0 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
289d0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
289e0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
289f0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
28a00 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
28a10 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
28a20 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
28a30 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
28a40 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
28a50 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 the name.)^.**
28a60 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 ^Parameters of t
28a70 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
28a80 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
28a90 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
28aa0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
28ab0 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 referred to as "
28ac0 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e nameless" or "an
28ad0 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
28ae0 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rs"..**.** ^The
28af0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
28b00 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
28b10 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
28b20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c *.** ^If the val
28b30 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 ue N is out of r
28b40 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e ange or if the N
28b50 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 -th parameter is
28b60 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 .** nameless, th
28b70 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 en NULL is retur
28b80 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ned. ^The retur
28b90 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a ned string is.**
28ba0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 always in UTF-8
28bb0 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 encoding even i
28bc0 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 f the named para
28bd0 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 meter was.** ori
28be0 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 ginally specifie
28bf0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b d as UTF-16 in [
28c00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
28c10 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 6()] or.** [sqli
28c20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
28c30 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
28c40 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
28c50 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
28c60 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
28c70 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
28c80 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
28c90 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
28ca0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
28cb0 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 ex()]..*/.const
28cc0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 char *sqlite3_bi
28cd0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
28ce0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
28cf0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
28d00 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
28d10 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
28d20 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a h A Given Name.*
28d30 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
28d40 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
28d50 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
28d60 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
28d70 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
28d80 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
28d90 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
28da0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
28db0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
28dc0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
28dd0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
28de0 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
28df0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
28e00 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
28e10 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
28e20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
28e30 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
28e40 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
28e50 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
28e60 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
28e70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
28e80 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
28e90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
28ea0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
28eb0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
28ec0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
28ed0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
28ee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
28ef0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
28f00 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
28f10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
28f20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
28f30 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
28f40 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 arameter_index(s
28f50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f qlite3_stmt*, co
28f60 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
28f70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28f80 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e F: Reset All Bin
28f90 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 dings On A Prepa
28fa0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a red Statement.**
28fb0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f .** ^Contrary to
28fc0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f the intuition o
28fd0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 f many, [sqlite3
28fe0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e _reset()] does n
28ff0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 ot reset.** the
29000 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
29010 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f ob | bindings] o
29020 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
29030 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 atement]..** ^Us
29040 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
29050 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 o reset all host
29060 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e parameters to N
29070 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
29080 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
29090 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
290a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
290b0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f EF: Number Of Co
290c0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c lumns In A Resul
290d0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 t Set.**.** ^Ret
290e0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
290f0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
29100 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
29110 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
29120 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29130 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 nt]. ^This routi
29140 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
29150 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a pStmt is an SQL.
29160 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ** statement tha
29170 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 t does not retur
29180 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d n data (for exam
29190 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
291a0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
291b0 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
291c0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 count()].*/.int
291d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
291e0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
291f0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
29200 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
29210 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
29220 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e sult Set.**.** ^
29230 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
29240 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
29250 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
29260 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
29270 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
29280 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
29290 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 ] statement. ^T
292a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
292b0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
292c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
292d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
292e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
292f0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
29300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29310 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
29320 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
29330 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
29340 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
29350 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 . ^The first pa
29360 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
29370 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29380 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
29390 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
293a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e CT] statement. ^
293b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
293c0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
293d0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e olumn number. ^
293e0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
293f0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
29400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
29410 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
29420 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
29430 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
29440 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29450 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
29460 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
29470 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
29480 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
29490 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
294a0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
294b0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
294c0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
294d0 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
294e0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
294f0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
29500 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
29510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
29520 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
29530 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
29540 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
29550 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 .**.** ^If sqlit
29560 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
29570 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
29580 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
29590 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
295a0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
295b0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
295c0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
295d0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
295e0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
295f0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
29600 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
29610 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
29620 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
29630 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
29640 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
29650 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
29660 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
29670 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
29680 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
29690 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
296a0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
296b0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
296c0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
296d0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
296e0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f the next..*/.co
296f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
29700 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 3_column_name(sq
29710 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
29720 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 N);.const void
29730 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
29740 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
29750 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
29760 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
29770 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
29780 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
29790 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
297a0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
297b0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
297c0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
297d0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
297e0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
297f0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
29800 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
29810 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
29820 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
29830 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
29840 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
29850 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
29860 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
29870 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
29880 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
29890 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
298a0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
298b0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
298c0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
298d0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
298e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
298f0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
29900 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
29910 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
29920 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
29930 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
29940 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
29950 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
29960 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
29970 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
29980 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
29990 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
299a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
299b0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
299c0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
299d0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
299e0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
299f0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
29a00 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
29a10 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
29a20 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
29a30 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
29a40 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
29a50 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
29a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
29a70 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
29a80 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
29a90 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
29aa0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
29ab0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
29ac0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
29ad0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
29ae0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
29af0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
29b00 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
29b10 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
29b20 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
29b30 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
29b40 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
29b50 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
29b60 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
29b70 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
29b80 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
29b90 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
29ba0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
29bb0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
29bc0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
29bd0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
29be0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
29bf0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
29c00 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
29c10 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
29c20 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
29c30 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
29c40 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
29c50 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
29c60 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
29c70 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
29c80 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
29c90 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
29ca0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
29cb0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
29cc0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
29cd0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
29ce0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
29cf0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
29d00 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
29d10 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
29d20 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
29d30 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
29d40 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
29d50 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
29d60 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
29d70 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
29d80 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
29d90 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
29da0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
29db0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
29dc0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
29dd0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
29de0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
29df0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
29e00 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
29e10 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
29e20 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
29e30 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
29e40 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
29e50 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
29e60 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
29e70 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
29e80 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
29e90 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
29ea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
29eb0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
29ec0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
29ed0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
29ee0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
29ef0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
29f00 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
29f10 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
29f20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
29f30 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
29f40 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
29f50 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
29f60 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
29f70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
29f80 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
29f90 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
29fa0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
29fb0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
29fc0 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
29fd0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
29fe0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
29ff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2a000 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2a010 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2a020 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2a030 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2a040 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
2a050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a060 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
2a070 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2a080 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2a090 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
2a0a0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2a0b0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2a0c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2a0d0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2a0e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2a0f0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2a100 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2a110 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2a120 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2a130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a140 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2a150 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2a160 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 Result.**.** ^(T
2a170 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2a180 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
2a190 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2a1a0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
2a1b0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
2a1c0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2a1d0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
2a1e0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
2a1f0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
2a200 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
2a210 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
2a220 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
2a230 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2a240 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
2a250 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
2a260 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
2a270 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
2a280 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2a290 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2a2a0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
2a2b0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2a2c0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
2a2d0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2a2e0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
2a2f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2a300 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
2a310 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
2a320 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
2a330 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2a340 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
2a350 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
2a360 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
2a370 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
2a380 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
2a390 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
2a3a0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
2a3b0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
2a3c0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
2a3d0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
2a3e0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
2a3f0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
2a400 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
2a410 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
2a420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
2a430 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
2a440 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
2a450 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2a460 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
2a470 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
2a480 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
2a490 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
2a4a0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
2a4b0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
2a4c0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
2a4d0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
2a4e0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
2a4f0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
2a500 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
2a510 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
2a520 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
2a530 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
2a540 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
2a550 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
2a560 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
2a570 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
2a580 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
2a590 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
2a5a0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
2a5b0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
2a5c0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
2a5d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
2a5e0 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
2a5f0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2a600 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2a610 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
2a620 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2a630 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2a640 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
2a650 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
2a660 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
2a670 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a680 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
2a690 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
2a6a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2a6b0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
2a6c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2a6d0 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
2a6e0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2a6f0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
2a700 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
2a710 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2a720 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
2a730 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
2a740 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
2a750 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
2a760 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
2a770 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
2a780 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
2a790 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
2a7a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
2a7b0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
2a7c0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
2a7d0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
2a7e0 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
2a7f0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
2a800 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
2a810 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2a820 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2a830 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2a840 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
2a850 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
2a860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2a870 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2a880 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
2a890 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
2a8a0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
2a8b0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2a8c0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
2a8d0 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
2a8e0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
2a8f0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
2a900 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
2a910 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
2a920 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2a930 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2a940 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
2a950 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
2a960 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2a970 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
2a980 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
2a990 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
2a9a0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
2a9b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2a9c0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
2a9d0 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
2a9e0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2a9f0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
2aa00 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
2aa10 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
2aa20 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
2aa30 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
2aa40 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
2aa50 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
2aa60 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
2aa70 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
2aa80 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
2aa90 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
2aaa0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
2aab0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
2aac0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
2aad0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2aae0 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
2aaf0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
2ab00 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
2ab10 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
2ab20 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
2ab30 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
2ab40 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 an.** explicit t
2ab50 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
2ab60 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
2ab70 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
2ab80 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
2ab90 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
2aba0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d ^[SQLITE_DONE] m
2abb0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
2abc0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
2abd0 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
2abe0 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
2abf0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2ac00 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2ac10 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
2ac20 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
2ac30 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
2ac40 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
2ac50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
2ac60 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
2ac70 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
2ac80 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2ac90 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e l state..**.** ^
2aca0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2acb0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
2acc0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
2acd0 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
2ace0 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
2acf0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
2ad00 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
2ad10 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
2ad20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
2ad30 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
2ad40 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
2ad50 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
2ad60 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
2ad70 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
2ad80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2ad90 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
2ada0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
2adb0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
2adc0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2add0 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
2ade0 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
2adf0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
2ae00 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
2ae10 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
2ae20 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
2ae30 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
2ae40 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
2ae50 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
2ae60 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
2ae70 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
2ae80 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2ae90 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 errmsg()]..** ^W
2aea0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
2aeb0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
2aec0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
2aed0 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
2aee0 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
2aef0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
2af00 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
2af10 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
2af20 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
2af30 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
2af40 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2af50 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
2af60 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2af70 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 tatement]. ^In
2af80 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2af90 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
2afa0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
2afb0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
2afc0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
2afd0 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
2afe0 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
2aff0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2b000 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
2b010 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
2b020 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
2b030 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
2b040 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
2b050 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2b060 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
2b070 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
2b080 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
2b090 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
2b0a0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
2b0b0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
2b0c0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
2b0d0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
2b0e0 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
2b0f0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
2b100 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2b110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2b120 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
2b130 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
2b140 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
2b150 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
2b160 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 ..**.** For all
2b170 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2b180 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 te up to and inc
2b190 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c luding 3.6.23.1,
2b1a0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 a call to.** [s
2b1b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2b1c0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 was required aft
2b1d0 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
2b1e0 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 ) returned anyth
2b1f0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 ing.** other tha
2b200 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 n [SQLITE_ROW] b
2b210 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 efore any subseq
2b220 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 uent invocation
2b230 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 of.** sqlite3_st
2b240 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 ep(). Failure t
2b250 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 o reset the prep
2b260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
2b270 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
2b280 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 3_reset()] would
2b290 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 result in an [S
2b2a0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 QLITE_MISUSE] re
2b2b0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c turn from.** sql
2b2c0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 ite3_step(). Bu
2b2d0 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 t after version
2b2e0 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 3.6.23.1, sqlite
2b2f0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
2b300 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
2b310 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
2b320 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
2b330 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
2b340 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
2b350 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
2b360 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
2b370 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
2b380 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
2b390 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
2b3a0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
2b3b0 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
2b3c0 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
2b3d0 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
2b3e0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
2b3f0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
2b400 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
2b410 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
2b420 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
2b430 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
2b440 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
2b450 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
2b460 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
2b470 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
2b480 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2b490 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
2b4a0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
2b4b0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
2b4c0 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
2b4d0 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
2b4e0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
2b4f0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
2b500 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
2b510 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
2b520 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
2b530 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
2b540 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2b550 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2b560 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
2b570 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
2b580 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
2b590 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
2b5a0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
2b5b0 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
2b5c0 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
2b5d0 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
2b5e0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
2b5f0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
2b600 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
2b610 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
2b620 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
2b630 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
2b640 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
2b650 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
2b660 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2b670 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2b680 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
2b690 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
2b6a0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
2b6b0 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2b6c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2b6d0 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
2b6e0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
2b6f0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2b700 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
2b710 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
2b720 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2b730 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
2b740 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2b750 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
2b760 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2b770 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
2b780 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2b790 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
2b7a0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
2b7b0 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 ult set.**.** ^T
2b7c0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2b7d0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
2b7e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
2b7f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2b800 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
2b810 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2b820 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
2b830 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b840 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
2b850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2b860 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
2b870 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
2b880 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
2b890 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
2b8a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
2b8b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b8c0 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
2b8d0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
2b8e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2b8f0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
2b900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2b910 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
2b920 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
2b930 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
2b940 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
2b950 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2b960 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2b970 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
2b980 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2b990 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2b9a0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
2b9b0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2b9c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2b9d0 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
2b9e0 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
2b9f0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
2ba00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2ba10 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2ba20 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
2ba30 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
2ba40 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
2ba50 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
2ba60 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
2ba70 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
2ba80 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
2ba90 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
2baa0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
2bab0 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
2bac0 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
2bad0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2bae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2baf0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 _count()].*/.int
2bb00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2bb10 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2bb20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2bb30 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
2bb40 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
2bb50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
2bb60 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
2bb70 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
2bb80 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
2bb90 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
2bba0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
2bbb0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2bbc0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
2bbd0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
2bbe0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
2bbf0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
2bc00 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
2bc10 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
2bc20 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
2bc30 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
2bc40 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
2bc50 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
2bc60 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
2bc70 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
2bc80 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
2bc90 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
2bca0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
2bcb0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
2bcc0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
2bcd0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
2bce0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
2bcf0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
2bd00 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
2bd10 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
2bd20 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
2bd30 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
2bd40 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
2bd50 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
2bd60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
2bd70 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
2bd80 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
2bd90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
2bda0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
2bdb0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
2bdc0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
2bdd0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
2bde0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
2bdf0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2be00 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
2be10 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
2be20 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
2be30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2be40 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
2be50 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
2be60 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
2be70 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
2be80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2be90 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
2bea0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
2beb0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
2bec0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2bed0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2bee0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
2bef0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
2bf00 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
2bf10 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
2bf20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
2bf30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2bf40 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2bf50 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2bf60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2bf70 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2bf80 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2bf90 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2bfa0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2bfb0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2bfc0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2bfd0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2bfe0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2bff0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2c000 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2c010 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2c020 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2c030 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2c040 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
2c050 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2c060 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2c070 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2c080 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
2c090 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2c0a0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
2c0b0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
2c0c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2c0d0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
2c0e0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
2c0f0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2c100 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
2c110 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
2c120 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
2c130 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
2c140 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
2c150 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2c160 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
2c170 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
2c180 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
2c190 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2c1a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2c1b0 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2c1c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2c1d0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
2c1e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2c1f0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
2c200 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
2c210 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
2c220 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
2c230 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
2c240 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2c250 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
2c260 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2c270 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2c280 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
2c290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2c2a0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
2c2b0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2c2c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2c2d0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
2c2e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2c2f0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
2c300 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2c310 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2c320 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2c330 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
2c340 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
2c350 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
2c360 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2c370 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
2c380 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2c390 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2c3a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2c3b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2c3c0 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
2c3d0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
2c3e0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
2c3f0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
2c400 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
2c410 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
2c420 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2c430 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2c440 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2c450 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2c460 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2c470 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2c480 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2c490 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2c4a0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2c4b0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2c4c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2c4d0 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2c4e0 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2c4f0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2c500 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2c510 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2c520 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2c530 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2c540 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2c550 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2c560 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2c570 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2c580 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2c590 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2c5a0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2c5b0 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2c5c0 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2c5d0 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2c5e0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2c5f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2c600 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2c610 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2c620 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2c630 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2c640 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2c650 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2c660 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2c670 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2c680 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2c690 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2c6a0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2c6b0 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2c6c0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2c6d0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2c6e0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2c6f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2c700 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2c710 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2c720 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2c730 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2c740 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2c750 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2c760 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2c770 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2c780 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2c790 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2c7a0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2c7b0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2c7c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2c7d0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2c7e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2c7f0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2c800 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2c810 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2c820 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2c830 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2c840 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2c850 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2c860 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2c870 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2c880 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2c890 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2c8a0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2c8b0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2c8c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c8d0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2c8e0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2c8f0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2c900 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2c910 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2c920 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2c930 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2c940 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2c950 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2c960 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2c970 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2c980 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2c990 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2c9a0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2c9b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2c9c0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2c9d0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2c9e0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2c9f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2ca00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2ca10 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2ca20 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2ca30 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2ca40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2ca50 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2ca60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2ca70 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2ca80 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2ca90 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2caa0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2cab0 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2cac0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2cad0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2cae0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2caf0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2cb00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2cb10 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2cb20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2cb30 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2cb40 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2cb50 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2cb60 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2cb70 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2cb80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2cb90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2cba0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2cbb0 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2cbc0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2cbd0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
2cbe0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2cbf0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2cc00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2cc10 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2cc20 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2cc30 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2cc40 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 * ^The object re
2cc50 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2cc60 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2cc70 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2cc80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2cc90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2cca0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
2ccb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2ccc0 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
2ccd0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
2cce0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2ccf0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2cd00 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2cd10 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
2cd20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2cd30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2cd40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2cd50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2cd60 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
2cd70 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
2cd80 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
2cd90 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
2cda0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
2cdb0 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
2cdc0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2cdd0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
2cde0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2cdf0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
2ce00 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2ce10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
2ce20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
2ce30 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2ce40 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
2ce50 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a opriate. ^For.*
2ce60 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2ce70 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2ce80 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2ce90 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2cea0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2ceb0 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2cec0 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2ced0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2cee0 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2cef0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2cf00 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 atically. ^(The
2cf10 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
2cf20 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
2cf30 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
2cf40 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
2cf50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2cf60 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2cf70 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2cf80 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
2cf90 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
2cfa0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
2cfb0 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
2cfc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2cfd0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2cfe0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2cff0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
2d000 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
2d010 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
2d020 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
2d030 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2d040 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2d050 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
2d060 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
2d070 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2d080 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2d090 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 td> Result is NU
2d0a0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 LL pointer.** <t
2d0b0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
2d0c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2d0d0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d td> Convert from
2d0e0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 integer to floa
2d0f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e t.** <tr><td> IN
2d100 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 TEGER <td> TE
2d110 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 XT <td> ASCII
2d120 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
2d130 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 e integer.** <tr
2d140 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
2d150 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
2d160 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 d> Same as INTEG
2d170 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e ER->TEXT.** <tr>
2d180 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
2d190 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 d> INTEGER <td
2d1a0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 > Convert from f
2d1b0 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a loat to integer.
2d1c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
2d1d0 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 AT <td> TEXT
2d1e0 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 <td> ASCII r
2d1f0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 endering of the
2d200 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2d210 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
2d220 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 BLOB <td> S
2d230 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 ame as FLOAT->TE
2d240 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 XT.** <tr><td>
2d250 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 TEXT <td> INT
2d260 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 EGER <td> Use
2d270 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
2d280 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2d290 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2d2a0 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 Use atof().** <t
2d2b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2d2c0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
2d2d0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a td> No change.**
2d2e0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
2d2f0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
2d300 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 <td> Convert t
2d310 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 o TEXT then use
2d320 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 atoi().** <tr><t
2d330 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
2d340 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2d350 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 Convert to TEXT
2d360 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a then use atof().
2d370 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
2d380 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 B <td> TEXT
2d390 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a <td> Add a z
2d3a0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 ero terminator i
2d3b0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 f needed.** </ta
2d3c0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 ble>.** </blockq
2d3d0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 uote>)^.**.** Th
2d3e0 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 e table above ma
2d3f0 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f kes reference to
2d400 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 standard C libr
2d410 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 ary functions at
2d420 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 oi().** and atof
2d430 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 (). SQLite does
2d440 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 not really use
2d450 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
2d460 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 It has its.**
2d470 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 own equivalent i
2d480 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 nternal routines
2d490 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e . The atoi() an
2d4a0 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 d atof() names a
2d4b0 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 re.** used in th
2d4c0 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 e table for brev
2d4d0 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 ity and because
2d4e0 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 they are familia
2d4f0 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 r to most.** C p
2d500 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a rogrammers..**.*
2d510 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e * Note that when
2d520 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2d530 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 s occur, pointer
2d540 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 s returned by pr
2d550 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ior.** calls to
2d560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2d570 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 lob(), sqlite3_c
2d580 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e olumn_text(), an
2d590 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d/or.** sqlite3_
2d5a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
2d5b0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 may be invalidat
2d5c0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 ed..** Type conv
2d5d0 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e ersions and poin
2d5e0 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e ter invalidation
2d5f0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a s might occur.**
2d600 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e in the followin
2d610 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c g cases:.**.** <
2d620 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
2d630 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2d640 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 is a BLOB and sq
2d650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2d660 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 t() or.** s
2d670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2d680 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
2d690 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e . A zero-termin
2d6a0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 ator might.**
2d6b0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 need to be ad
2d6c0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e ded to the strin
2d6d0 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 g.</li>.** <li>
2d6e0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2d6f0 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 ent is UTF-8 tex
2d700 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
2d710 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f lumn_bytes16() o
2d720 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
2d730 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2d740 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
2d750 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
2d760 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
2d770 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f to UTF-16.</
2d780 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
2d790 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
2d7a0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
2d7b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2d7c0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
2d7d0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
2d7e0 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 umn_text() is ca
2d7f0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
2d800 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
2d810 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
2d820 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c UTF-8.</li>.** <
2d830 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 /ul>.**.** ^Conv
2d840 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
2d850 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
2d860 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
2d870 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
2d880 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
2d890 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
2d8a0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
2d8b0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
2d8c0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
2d8d0 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
2d8e0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 prior pointer re
2d8f0 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 ferences will ha
2d900 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
2d910 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
2d920 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
2d930 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
2d940 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
2d950 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
2d960 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
2d970 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
2d980 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
2d990 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
2d9a0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
2d9b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
2d9c0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f t and easiest to
2d9d0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 remember policy
2d9e0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 is to invoke th
2d9f0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 ese routines.**
2da00 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f in one of the fo
2da10 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a llowing ways:.**
2da20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 .** <ul>.** <li
2da30 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2da40 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 text() followed
2da50 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2da60 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
2da70 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
2da80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c olumn_blob() fol
2da90 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
2daa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c _column_bytes()<
2dab0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c /li>.** <li>sql
2dac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2dad0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 16() followed by
2dae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2daf0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a bytes16()</li>.*
2db00 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e * </ul>.**.** In
2db10 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f other words, yo
2db20 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 u should call sq
2db30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2db40 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t(),.** sqlite3_
2db50 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f column_blob(), o
2db60 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2db70 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 _text16() first
2db80 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 to force the res
2db90 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ult.** into the
2dba0 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 desired format,
2dbb0 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 then invoke sqli
2dbc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2dbd0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 () or.** sqlite3
2dbe0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2dbf0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 ) to find the si
2dc00 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ze of the result
2dc10 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 . Do not mix ca
2dc20 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 lls.** to sqlite
2dc30 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 3_column_text()
2dc40 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
2dc50 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 n_blob() with ca
2dc60 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
2dc70 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2dc80 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d (), and do not m
2dc90 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ix calls to sqli
2dca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2dcb0 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 6().** with call
2dcc0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c s to sqlite3_col
2dcd0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a umn_bytes()..**.
2dce0 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 ** ^The pointers
2dcf0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 returned are va
2dd00 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 lid until a type
2dd10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
2dd20 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 rs as.** describ
2dd30 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 ed above, or unt
2dd40 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 il [sqlite3_step
2dd50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2dd60 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
2dd70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2dd80 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 ()] is called.
2dd90 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 ^The memory spac
2dda0 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 e used to hold s
2ddb0 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c trings.** and BL
2ddc0 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 OBs is freed aut
2ddd0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 omatically. Do
2dde0 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 <b>not</b> pass
2ddf0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 the pointers ret
2de00 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 urned.** [sqlite
2de10 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 3_column_blob()]
2de20 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d , [sqlite3_colum
2de30 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 n_text()], etc.
2de40 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 into.** [sqlite3
2de50 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _free()]..**.**
2de60 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c ^(If a memory al
2de70 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f location error o
2de80 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 ccurs during the
2de90 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 evaluation of a
2dea0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 ny.** of these r
2deb0 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 outines, a defau
2dec0 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 lt value is retu
2ded0 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 rned. The defau
2dee0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 lt value.** is e
2def0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 ither the intege
2df00 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e r 0, the floatin
2df10 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 g point number 0
2df20 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a .0, or a NULL.**
2df30 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 pointer. Subse
2df40 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b quent calls to [
2df50 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
2df60 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a )] will return.*
2df70 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d * [SQLITE_NOMEM]
2df80 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 .)^.*/.const voi
2df90 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2dfa0 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
2dfb0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2dfc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2dfd0 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 umn_bytes(sqlite
2dfe0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2dff0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2e000 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 column_bytes16(s
2e010 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2e020 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 t iCol);.double
2e030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2e040 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
2e050 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2e060 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2e070 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
2e080 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2e090 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 .sqlite3_int64 s
2e0a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
2e0b0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
2e0c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
2e0d0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
2e0e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
2e0f0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 n_text(sqlite3_s
2e100 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2e110 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
2e120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2e130 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2e140 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
2e150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2e160 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
2e170 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 t*, int iCol);.s
2e180 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 qlite3_value *sq
2e190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
2e1a0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
2e1b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a , int iCol);../*
2e1c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
2e1d0 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 stroy A Prepared
2e1e0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
2e1f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2e200 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 ite3_finalize()
2e210 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c function is call
2e220 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b ed to delete a [
2e230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e240 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 nt]..** ^If the
2e250 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
2e260 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 uation of the st
2e270 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 atement encounte
2e280 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a red no errors.**
2e290 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 or if the state
2e2a0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 ment is never be
2e2b0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 en evaluated, th
2e2c0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c en sqlite3_final
2e2d0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a ize() returns.**
2e2e0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 SQLITE_OK. ^If
2e2f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
2e300 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 evaluation of s
2e310 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 tatement S faile
2e320 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 d, then.** sqlit
2e330 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 e3_finalize(S) r
2e340 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f eturns the appro
2e350 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f priate [error co
2e360 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e de] or.** [exten
2e370 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e ded error code].
2e380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2e390 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 te3_finalize(S)
2e3a0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 routine can be c
2e3b0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 alled at any poi
2e3c0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 nt during.** the
2e3d0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b life cycle of [
2e3e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e3f0 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 nt] S:.** before
2e400 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 statement S is
2e410 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 ever evaluated,
2e420 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 after.** one or
2e430 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 more calls to [s
2e440 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c qlite3_reset()],
2e450 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 or after any ca
2e460 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 ll.** to [sqlite
2e470 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 3_step()] regard
2e480 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
2e490 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 or not the state
2e4a0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 ment has.** comp
2e4b0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e leted execution.
2e4c0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 .**.** ^Invoking
2e4d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2e4e0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f e() on a NULL po
2e4f0 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c inter is a harml
2e500 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a ess no-op..**.**
2e510 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
2e520 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 must finalize e
2e530 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 very [prepared s
2e540 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 tatement] in ord
2e550 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 er to avoid.** r
2e560 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 esource leaks.
2e570 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 It is a grievous
2e580 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 error for the a
2e590 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 pplication to tr
2e5a0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 y to use.** a pr
2e5b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2e5c0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
2e5d0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 en finalized. A
2e5e0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 ny use of a prep
2e5f0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
2e600 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 t after it has b
2e610 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 een finalized ca
2e620 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 n result in unde
2e630 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 fined and.** und
2e640 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f esirable behavio
2e650 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 r such as segfau
2e660 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 lts and heap cor
2e670 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 ruption..*/.int
2e680 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2e690 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
2e6a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
2e6b0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
2e6c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
2e6d0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 nt Object.**.**
2e6e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 The sqlite3_rese
2e6f0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 t() function is
2e700 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 called to reset
2e710 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2e720 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
2e730 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 back to its ini
2e740 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 tial state, read
2e750 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 y to be re-execu
2e760 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c ted..** ^Any SQL
2e770 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 statement varia
2e780 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 bles that had va
2e790 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 lues bound to th
2e7a0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 em using.** the
2e7b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2e7c0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e ob | sqlite3_bin
2e7d0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 d_*() API] retai
2e7e0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a n their values..
2e7f0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f ** Use [sqlite3_
2e800 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 clear_bindings()
2e810 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 ] to reset the b
2e820 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e indings..**.** ^
2e830 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 The [sqlite3_res
2e840 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 et(S)] interface
2e850 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 resets the [pre
2e860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2e870 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 S.** back to th
2e880 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 e beginning of i
2e890 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a ts program..**.*
2e8a0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
2e8b0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2e8c0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2e8d0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
2e8e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2e8f0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 S returned [SQLI
2e900 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 TE_ROW] or [SQLI
2e910 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 TE_DONE],.** or
2e920 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 if [sqlite3_step
2e930 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 (S)] has never b
2e940 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 efore been calle
2e950 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 d on S,.** then
2e960 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
2e970 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 )] returns [SQLI
2e980 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 TE_OK]..**.** ^I
2e990 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
2e9a0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 t call to [sqlit
2e9b0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 e3_step(S)] for
2e9c0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 the.** [prepared
2e9d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e statement] S in
2e9e0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 dicated an error
2e9f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 , then.** [sqlit
2ea00 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 e3_reset(S)] ret
2ea10 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 urns an appropri
2ea20 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
2ea30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ..**.** ^The [sq
2ea40 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
2ea50 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e interface does n
2ea60 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 ot change the va
2ea70 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b lues.** of any [
2ea80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2ea90 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 b|bindings] on t
2eaa0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2eab0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e tement] S..*/.in
2eac0 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 t sqlite3_reset(
2ead0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2eae0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2eaf0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 I3REF: Create Or
2eb00 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 Redefine SQL Fu
2eb10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f nctions.** KEYWO
2eb20 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 RDS: {function c
2eb30 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2eb40 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2eb50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2eb60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2eb70 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2eb80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2eb90 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2eba0 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 s}.**.** ^These
2ebb0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
2ebc0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
2ebd0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
2ebe0 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
2ebf0 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
2ec00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
2ec10 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
2ec20 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
2ec30 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
2ec40 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
2ec50 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
2ec60 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
2ec70 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 differences betw
2ec80 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 een.** these rou
2ec90 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 tines are the te
2eca0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 xt encoding expe
2ecb0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 cted for.** the
2ecc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
2ecd0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 (the name of th
2ece0 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 e function being
2ecf0 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 created).** and
2ed00 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 the presence or
2ed10 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 absence of a de
2ed20 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
2ed30 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 k for.** the app
2ed40 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
2ed50 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
2ed60 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
2ed70 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
2ed80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
2ed90 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
2eda0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
2edb0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 o be added. ^If
2edc0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
2edd0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
2ede0 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
2edf0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 onnection then a
2ee00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
2ee10 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
2ee20 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a must be added.*
2ee30 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 * to each databa
2ee40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 se connection se
2ee50 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 parately..**.**
2ee60 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
2ee70 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
2ee80 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
2ee90 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
2eea0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
2eeb0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 ned. ^The lengt
2eec0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 h of the name is
2eed0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 limited to 255
2eee0 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 bytes in a UTF-8
2eef0 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 .** representati
2ef00 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 on, exclusive of
2ef10 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
2ef20 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 ator. ^Note tha
2ef30 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 t the name.** le
2ef40 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
2ef50 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f UTF-8 bytes, no
2ef60 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 t characters nor
2ef70 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 UTF-16 bytes.
2ef80 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 .** ^Any attempt
2ef90 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
2efa0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
2efb0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
2efc0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
2efd0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 TE_MISUSE] being
2efe0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
2eff0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
2f000 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
2f010 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
2f020 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
2f030 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
2f040 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
2f050 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
2f060 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
2f070 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
2f080 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
2f090 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
2f0a0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
2f0b0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
2f0c0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
2f0d0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
2f0e0 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
2f0f0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
2f100 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
2f110 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
2f120 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
2f130 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
2f140 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
2f150 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
2f160 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2f170 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
2f180 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
2f190 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
2f1a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
2f1b0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
2f1c0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
2f1d0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
2f1e0 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
2f1f0 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 s. Every SQL fu
2f200 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 nction implement
2f210 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 ation must be ab
2f220 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 le to work.** wi
2f230 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 th UTF-8, UTF-16
2f240 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e le, or UTF-16be.
2f250 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 But some imple
2f260 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 mentations may b
2f270 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 e.** more effici
2f280 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 ent with one enc
2f290 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 oding than anoth
2f2a0 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 er. ^An applica
2f2b0 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f tion may.** invo
2f2c0 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 ke sqlite3_creat
2f2d0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 e_function() or
2f2e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2f2f0 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 unction16() mult
2f300 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 iple.** times wi
2f310 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 th the same func
2f320 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 tion but with di
2f330 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f fferent values o
2f340 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e f eTextRep..** ^
2f350 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d When multiple im
2f360 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 plementations of
2f370 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 the same functi
2f380 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 on are available
2f390 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c , SQLite.** will
2f3a0 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 pick the one th
2f3b0 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 at involves the
2f3c0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 least amount of
2f3d0 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e data conversion.
2f3e0 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 .** If there is
2f3f0 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d only a single im
2f400 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 plementation whi
2f410 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 ch does not care
2f420 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e what text.** en
2f430 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 coding is used,
2f440 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 then the fourth
2f450 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
2f460 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e be [SQLITE_ANY].
2f470 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 .**.** ^(The fif
2f480 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
2f490 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 an arbitrary poi
2f4a0 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 nter. The imple
2f4b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
2f4c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e .** function can
2f4d0 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 gain access to
2f4e0 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 this pointer usi
2f4f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ng [sqlite3_user
2f500 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a _data()].)^.**.*
2f510 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 * ^The sixth, se
2f520 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 venth and eighth
2f530 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 parameters, xFu
2f540 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 nc, xStep and xF
2f550 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 inal, are.** poi
2f560 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 nters to C-langu
2f570 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 age functions th
2f580 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 at implement the
2f590 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
2f5a0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e .** aggregate. ^
2f5b0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e A scalar SQL fun
2f5c0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 ction requires a
2f5d0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
2f5e0 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a of the xFunc.**
2f5f0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 callback only;
2f600 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 NULL pointers mu
2f610 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 st be passed as
2f620 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 the xStep and xF
2f630 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 inal.** paramete
2f640 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 rs. ^An aggregat
2f650 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 e SQL function r
2f660 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 equires an imple
2f670 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 mentation of xSt
2f680 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c ep.** and xFinal
2f690 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 and NULL pointe
2f6a0 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 r must be passed
2f6b0 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 for xFunc. ^To
2f6c0 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 delete an existi
2f6d0 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 ng.** SQL functi
2f6e0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c on or aggregate,
2f6f0 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 pass NULL point
2f700 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 ers for all thre
2f710 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 e function.** ca
2f720 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e llbacks..**.** ^
2f730 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 (If the ninth pa
2f740 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2f750 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2f760 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e on_v2() is not N
2f770 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 ULL,.** then it
2f780 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f is destructor fo
2f790 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
2f7a0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 n data pointer.
2f7b0 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 .** The destruct
2f7c0 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 or is invoked wh
2f7d0 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 en the function
2f7e0 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 is deleted, eith
2f7f0 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f er by being.** o
2f800 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 verloaded or whe
2f810 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
2f820 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
2f830 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 .)^.** ^The dest
2f840 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 ructor is also i
2f850 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 nvoked if the ca
2f860 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ll to.** sqlite3
2f870 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
2f880 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 _v2() fails..**
2f890 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 ^When the destru
2f8a0 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 ctor callback of
2f8b0 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d the tenth param
2f8c0 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c eter is invoked,
2f8d0 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 it.** is passed
2f8e0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
2f8f0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f nt which is a co
2f900 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 py of the applic
2f910 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 ation data .** p
2f920 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 ointer which was
2f930 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d the fifth param
2f940 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
2f950 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
2f960 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 v2()..**.** ^It
2f970 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
2f980 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c register multipl
2f990 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2f9a0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a s of the same.**
2f9b0 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 functions with
2f9c0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
2f9d0 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 t with either di
2f9e0 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 ffering numbers
2f9f0 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 of.** arguments
2fa00 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 or differing pre
2fa10 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f ferred text enco
2fa20 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 dings. ^SQLite
2fa30 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 will use.** the
2fa40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 implementation t
2fa50 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 hat most closely
2fa60 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 matches the way
2fa70 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a in which the.**
2fa80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
2fa90 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 used. ^A funct
2faa0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
2fab0 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 on with a non-ne
2fac0 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 gative.** nArg p
2fad0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 arameter is a be
2fae0 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 tter match than
2faf0 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 a function imple
2fb00 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a mentation with.*
2fb10 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 * a negative nAr
2fb20 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 g. ^A function
2fb30 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 where the prefer
2fb40 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
2fb50 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 g.** matches the
2fb60 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 database encodi
2fb70 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a ng is a better.*
2fb80 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 * match than a f
2fb90 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
2fba0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 e encoding is di
2fbb0 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 fferent. .** ^A
2fbc0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
2fbd0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
2fbe0 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 ference is betwe
2fbf0 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 en UTF16le and U
2fc00 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 TF16be.** is a c
2fc10 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e loser match than
2fc20 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
2fc30 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 e the encoding d
2fc40 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 ifference is.**
2fc50 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 between UTF8 and
2fc60 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 UTF16..**.** ^B
2fc70 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e uilt-in function
2fc80 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 s may be overloa
2fc90 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 ded by new appli
2fca0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
2fcb0 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 unctions..**.**
2fcc0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d ^An application-
2fcd0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
2fce0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
2fcf0 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 call other.** S
2fd00 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
2fd10 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 . However, such
2fd20 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a calls must not.
2fd30 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ** close the dat
2fd40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2fd50 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 nor finalize or
2fd60 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 reset the prepa
2fd70 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
2fd80 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 in which the fu
2fd90 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
2fda0 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 g..*/.int sqlite
2fdb0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2fdc0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 n(. sqlite3 *db
2fdd0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
2fde0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
2fdf0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
2fe00 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
2fe10 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
2fe20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
2fe30 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
2fe40 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
2fe50 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
2fe60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2fe70 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2fe80 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2fe90 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
2fea0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 context*).);.int
2feb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2fec0 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 function16(. sq
2fed0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
2fee0 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 st void *zFuncti
2fef0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
2ff00 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
2ff10 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
2ff20 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
2ff30 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
2ff40 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
2ff50 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
2ff60 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
2ff70 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
2ff80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
2ff90 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
2ffa0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
2ffb0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
2ffc0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
2ffd0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 n_v2(. sqlite3
2ffe0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 *db,. const cha
2fff0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 r *zFunctionName
30000 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
30010 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
30020 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
30030 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
30040 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
30050 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
30060 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
30070 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
30080 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
30090 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
300a0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
300b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 e3_context*),.
300c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
300d0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a void*).);../*.**
300e0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 CAPI3REF: Text
300f0 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 Encodings.**.**
30100 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 These constant d
30110 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f efine integer co
30120 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 des that represe
30130 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a nt the various.*
30140 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 * text encodings
30150 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
30160 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 Lite..*/.#define
30170 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 SQLITE_UTF8
30180 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
30190 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
301a0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
301b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 SQLITE_UTF16BE
301c0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
301d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 SQLITE_UTF16
301e0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 4 /* U
301f0 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f se native byte o
30200 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rder */.#define
30210 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 SQLITE_ANY
30220 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 5 /* sq
30230 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30240 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 ction only */.#d
30250 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
30260 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
30270 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
30280 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
30290 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
302a0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 3REF: Deprecated
302b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 Functions.** DE
302c0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 PRECATED.**.** T
302d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 hese functions a
302e0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e re [deprecated].
302f0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 In order to ma
30300 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 intain.** backwa
30310 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
30320 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 y with older cod
30330 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f e, these functio
30340 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 ns continue .**
30350 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
30360 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 However, new a
30370 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
30380 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 ld avoid.** the
30390 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e use of these fun
303a0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 ctions. To help
303b0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c encourage peopl
303c0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 e to avoid.** us
303d0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 ing these functi
303e0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 ons, we are not
303f0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f going to tell yo
30400 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a u what they do..
30410 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
30420 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 E_OMIT_DEPRECATE
30430 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 D.SQLITE_DEPRECA
30440 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
30450 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 aggregate_count(
30460 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
30470 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
30480 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
30490 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 _expired(sqlite3
304a0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f _stmt*);.SQLITE_
304b0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
304c0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f qlite3_transfer_
304d0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
304e0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f _stmt*, sqlite3_
304f0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 stmt*);.SQLITE_D
30500 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
30510 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 lite3_global_rec
30520 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 over(void);.SQLI
30530 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f TE_DEPRECATED vo
30540 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 id sqlite3_threa
30550 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b d_cleanup(void);
30560 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
30570 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d ED int sqlite3_m
30580 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 emory_alarm(void
30590 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
305a0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 3_int64,int),.
305b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
305c0 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 void*,sqlite
305d0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 3_int64);.#endif
305e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
305f0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 : Obtaining SQL
30600 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 Function Paramet
30610 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 er Values.**.**
30620 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 The C-language i
30630 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
30640 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
30650 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 nd aggregates us
30660 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f es.** this set o
30670 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 f interface rout
30680 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 ines to access t
30690 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c he parameter val
306a0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 ues on.** the fu
306b0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
306c0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ate..**.** The x
306d0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 Func (for scalar
306e0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 functions) or x
306f0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 Step (for aggreg
30700 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 ates) parameters
30710 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
30720 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
30730 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
30740 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
30750 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 6()].** define c
30760 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d allbacks that im
30770 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 plement the SQL
30780 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
30790 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 gregates..** The
307a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
307b0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b o these callback
307c0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 s is an array of
307d0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 pointers to.**
307e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
307f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30800 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 s. There is one
30810 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
30820 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 object for.** e
30830 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f ach parameter to
30840 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
30850 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e n. These routin
30860 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a es are used to.*
30870 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 * extract values
30880 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
30890 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
308a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 s..**.** These r
308b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c outines work onl
308c0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 y with [protecte
308d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
308e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 objects..** Any
308f0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 attempt to use
30900 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f these routines o
30910 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 n an [unprotecte
30920 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
30930 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c .** object resul
30940 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 ts in undefined
30950 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 behavior..**.**
30960 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
30970 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 work just like t
30980 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
30990 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
309a0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 functions].** ex
309b0 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 cept that these
309c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 routines take a
309d0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 single [protect
309e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
309f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e ] object.** poin
30a00 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 ter instead of a
30a10 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d [sqlite3_stmt*]
30a20 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 pointer and an
30a30 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e integer column n
30a40 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 umber..**.** ^Th
30a50 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
30a60 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 text16() interfa
30a70 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 ce extracts a UT
30a80 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 F-16 string.** i
30a90 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 n the native byt
30aa0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 e-order of the h
30ab0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 ost machine. ^T
30ac0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 he.** sqlite3_va
30ad0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 lue_text16be() a
30ae0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nd sqlite3_value
30af0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 _text16le() inte
30b00 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 rfaces.** extrac
30b10 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 t UTF-16 strings
30b20 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 as big-endian a
30b30 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e nd little-endian
30b40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
30b50 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
30b60 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
30b70 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 _type() interfac
30b80 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 e attempts to ap
30b90 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 ply.** numeric a
30ba0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 ffinity to the v
30bb0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e alue. This mean
30bc0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 s that an attemp
30bd0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 t is.** made to
30be0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 convert the valu
30bf0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 e to an integer
30c00 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e or floating poin
30c10 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 t. If.** such a
30c20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 conversion is p
30c30 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 ossible without
30c40 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 loss of informat
30c50 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a ion (in other.**
30c60 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 words, if the v
30c70 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 alue is a string
30c80 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 that looks like
30c90 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 a number).** th
30ca0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f en the conversio
30cb0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 n is performed.
30cc0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f Otherwise no co
30cd0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e nversion occurs.
30ce0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
30cf0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
30d00 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 pe] after conver
30d10 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 sion is returned
30d20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 .)^.**.** Please
30d30 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 pay particular
30d40 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 attention to the
30d50 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 fact that the p
30d60 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a ointer returned.
30d70 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
30d80 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 _value_blob()],
30d90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
30da0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 ext()], or.** [s
30db0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
30dc0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e t16()] can be in
30dd0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 validated by a s
30de0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
30df0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 o.** [sqlite3_va
30e00 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 lue_bytes()], [s
30e10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
30e20 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 es16()], [sqlite
30e30 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 3_value_text()],
30e40 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
30e50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e value_text16()].
30e60 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
30e70 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 tines must be ca
30e80 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 lled from the sa
30e90 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 me thread as.**
30ea0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
30eb0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 that supplied t
30ec0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
30ed0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a e*] parameters..
30ee0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 */.const void *s
30ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
30f00 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a b(sqlite3_value*
30f10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 );.int sqlite3_v
30f20 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 alue_bytes(sqlit
30f30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
30f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
30f50 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 tes16(sqlite3_va
30f60 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 lue*);.double sq
30f70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
30f80 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
30f90 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
30fa0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 value_int(sqlite
30fb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 3_value*);.sqlit
30fc0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
30fd0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c _value_int64(sql
30fe0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f ite3_value*);.co
30ff0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 nst unsigned cha
31000 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r *sqlite3_value
31010 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 _text(sqlite3_va
31020 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
31030 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
31040 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
31050 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 value*);.const v
31060 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c oid *sqlite3_val
31070 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 ue_text16le(sqli
31080 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
31090 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
310a0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
310b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
310c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
310d0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ue_type(sqlite3_
310e0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
310f0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 ite3_value_numer
31100 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ic_type(sqlite3_
31110 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 value*);../*.**
31120 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
31130 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 Aggregate Funct
31140 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a ion Context.**.*
31150 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * Implementation
31160 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 s of aggregate S
31170 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 QL functions use
31180 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
31190 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
311a0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 ory for storing
311b0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a their state..**.
311c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 ** ^The first ti
311d0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 me the sqlite3_a
311e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
311f0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 (C,N) routine is
31200 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 called .** for
31210 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 a particular agg
31220 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c regate function,
31230 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 SQLite.** alloc
31240 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 ates N of memory
31250 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 , zeroes out tha
31260 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 t memory, and re
31270 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a turns a pointer.
31280 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 ** to the new me
31290 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 mory. ^On second
312a0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 and subsequent
312b0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 calls to.** sqli
312c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
312d0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 ntext() for the
312e0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 same aggregate f
312f0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 unction instance
31300 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 ,.** the same bu
31310 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 ffer is returned
31320 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 . Sqlite3_aggre
31330 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 gate_context() i
31340 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 s normally.** ca
31350 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 lled once for ea
31360 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ch invocation of
31370 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 the xStep callb
31380 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 ack and then one
31390 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 .** last time wh
313a0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 en the xFinal ca
313b0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
313c0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f d. ^(When no ro
313d0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 ws match.** an a
313e0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 ggregate query,
313f0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c the xStep() call
31400 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 back of the aggr
31410 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a egate function.*
31420 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
31430 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 is never called
31440 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 and xFinal() is
31450 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 called exactly
31460 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 once..** In thos
31470 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 e cases, sqlite3
31480 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
31490 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 xt() might be ca
314a0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 lled for the.**
314b0 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 first time from
314c0 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e within xFinal().
314d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
314e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
314f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
31500 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e tine returns a N
31510 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 ULL pointer .**
31520 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 when first calle
31530 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 d if N is less t
31540 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
31550 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d zero or if a mem
31560 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 ory.** allocate
31570 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a error occurs..**
31580 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 .** ^(The amount
31590 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 of space alloca
315a0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 ted by sqlite3_a
315b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
315c0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 (C,N) is.** dete
315d0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 rmined by the N
315e0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 parameter on fir
315f0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 st successful ca
31600 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 ll. Changing th
31610 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 e.** value of N
31620 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
31630 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 ll to sqlite3_ag
31640 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
31650 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 ) within.** the
31660 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 same aggregate f
31670 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 unction instance
31680 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 will not resize
31690 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 the memory.** a
316a0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 llocation.)^ Wi
316b0 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 thin the xFinal
316c0 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 callback, it is
316d0 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 customary to set
316e0 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 .** N=0 in calls
316f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 to sqlite3_aggr
31700 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
31710 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a N) so that no .*
31720 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f * pointless memo
31730 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f ry allocations o
31740 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c ccur..**.** ^SQL
31750 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ite automaticall
31760 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f y frees the memo
31770 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ry allocated by
31780 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 .** sqlite3_aggr
31790 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
317a0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 when the aggrega
317b0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 te query conclud
317c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
317d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 rst parameter mu
317e0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 st be a copy of
317f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
31800 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 context | SQL fu
31810 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 nction context]
31820 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 that is the firs
31830 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 t parameter.** t
31840 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 o the xStep or x
31850 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 Final callback r
31860 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c outine that impl
31870 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 ements the aggre
31880 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gate.** function
31890 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
318a0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
318b0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
318c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
318d0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 h.** the aggrega
318e0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
318f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 is running..*/.v
31900 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 oid *sqlite3_agg
31910 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 regate_context(s
31920 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
31930 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f int nBytes);../
31940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 *.** CAPI3REF: U
31950 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e ser Data For Fun
31960 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 ctions.**.** ^Th
31970 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 e sqlite3_user_d
31980 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
31990 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
319a0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
319b0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 that was the pU
319c0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 serData paramete
319d0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d r (the 5th param
319e0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
319f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
31a00 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
31a10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
31a20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
31a30 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
31a40 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
31a50 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
31a60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
31a70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
31a80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
31a90 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
31aa0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
31ab0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
31ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
31ad0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
31ae0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 running..*/.voi
31af0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f d *sqlite3_user_
31b00 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
31b10 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 text*);../*.** C
31b20 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
31b30 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 e Connection For
31b40 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
31b50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
31b60 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
31b70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
31b80 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
31b90 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
31ba0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
31bb0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 nnection] (the 1
31bc0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a st parameter).**
31bd0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
31be0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
31bf0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
31c00 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
31c10 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
31c20 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
31c30 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
31c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
31c50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
31c60 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 ..*/.sqlite3 *sq
31c70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
31c80 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f _handle(sqlite3_
31c90 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a context*);../*.*
31ca0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 * CAPI3REF: Func
31cb0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 tion Auxiliary D
31cc0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f ata.**.** The fo
31cd0 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 llowing two func
31ce0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 tions may be use
31cf0 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 d by scalar SQL
31d00 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 functions to.**
31d10 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 associate metada
31d20 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 ta with argument
31d30 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 values. If the
31d40 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 same value is pa
31d50 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 ssed to.** multi
31d60 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 ple invocations
31d70 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 of the same SQL
31d80 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 function during
31d90 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c query execution,
31da0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 under.** some c
31db0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 ircumstances the
31dc0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 associated meta
31dd0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 data may be pres
31de0 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a erved. This may.
31df0 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 ** be used, for
31e00 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 example, to add
31e10 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 a regular-expres
31e20 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 sion matching sc
31e30 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e alar.** function
31e40 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 . The compiled v
31e50 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 ersion of the re
31e60 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e gular expression
31e70 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a is stored as.**
31e80 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 metadata associ
31e90 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 ated with the SQ
31ea0 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 L value passed a
31eb0 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 s the regular ex
31ec0 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 pression.** patt
31ed0 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c ern. The compil
31ee0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 ed regular expre
31ef0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 ssion can be reu
31f00 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a sed on multiple.
31f10 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f ** invocations o
31f20 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
31f30 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 ion so that the
31f40 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e original pattern
31f50 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 string.** does
31f60 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 not need to be r
31f70 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 ecompiled on eac
31f80 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a h invocation..**
31f90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
31fa0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _get_auxdata() i
31fb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
31fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
31fd0 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 e metadata.** as
31fe0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 sociated by the
31ff0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
32000 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 ata() function w
32010 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 ith the Nth argu
32020 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f ment.** value to
32030 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
32040 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
32050 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 n. ^If no metada
32060 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 ta has been ever
32070 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 .** been set for
32080 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e the Nth argumen
32090 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f t of the functio
320a0 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 n, or if the cor
320b0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 responding.** fu
320c0 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 nction parameter
320d0 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e has changed sin
320e0 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 ce the meta-data
320f0 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 was set,.** the
32100 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 n sqlite3_get_au
32110 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 xdata() returns
32120 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
32130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
32140 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
32150 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 interface saves
32160 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a the metadata.**
32170 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 pointed to by i
32180 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
32190 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 as the metadata
321a0 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a for the N-th.**
321b0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
321c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
321d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 ined function.
321e0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 Subsequent.** ca
321f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 lls to sqlite3_g
32200 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 et_auxdata() mig
32210 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 ht return this d
32220 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a ata, if it has.*
32230 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 * not been destr
32240 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 oyed..** ^If it
32250 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c is not NULL, SQL
32260 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 ite will invoke
32270 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a the destructor.*
32280 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e * function given
32290 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 by the 4th para
322a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
322b0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f _set_auxdata() o
322c0 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 n.** the metadat
322d0 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 a when the corre
322e0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f sponding functio
322f0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e n parameter chan
32300 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 ges.** or when t
32310 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
32320 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 completes, whic
32330 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 hever comes firs
32340 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 t..**.** SQLite
32350 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 is free to call
32360 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 the destructor a
32370 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 nd drop metadata
32380 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d on any.** param
32390 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 eter of any func
323a0 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 tion at any time
323b0 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 . ^The only gua
323c0 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a rantee is that.*
323d0 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 * the destructor
323e0 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 will be called
323f0 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 before the metad
32400 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a ata is dropped..
32410 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 **.** ^(In pract
32420 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 ice, metadata is
32430 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 preserved betwe
32440 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c en function call
32450 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 s for.** express
32460 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f ions that are co
32470 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c nstant at compil
32480 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 e time. This inc
32490 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a ludes literal.**
324a0 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 values and [par
324b0 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a ameters].)^.**.*
324c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
324d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
324e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
324f0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
32500 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32510 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
32520 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 .void *sqlite3_g
32530 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
32540 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
32550 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 N);.void sqlite
32560 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_set_auxdata(sq
32570 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32580 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f int N, void*, vo
32590 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a id (*)(void*));.
325a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
325b0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 : Constants Defi
325c0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 ning Special Des
325d0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 tructor Behavior
325e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
325f0 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 special values
32600 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 for the destruct
32610 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 or that is passe
32620 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
32630 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f inal argument to
32640 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
32650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
32660 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 lob()]. ^If the
32670 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
32680 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
32690 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
326a0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
326b0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
326c0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
326d0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
326e0 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
326f0 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
32700 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 yed. ^The.** SQ
32710 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 LITE_TRANSIENT v
32720 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 alue means that
32730 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c the content will
32740 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 likely change i
32750 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 n.** the near fu
32760 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 ture and that SQ
32770 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 Lite should make
32780 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
32790 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
327a0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 content before r
327b0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
327c0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e The typedef is n
327d0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b ecessary to work
327e0 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 around problems
327f0 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 in certain.** C
32800 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 ++ compilers. S
32810 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e ee ticket #2191.
32820 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 .*/.typedef void
32830 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 (*sqlite3_destr
32840 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 uctor_type)(void
32850 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 *);.#define SQLI
32860 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 TE_STATIC (
32870 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
32880 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 tor_type)0).#def
32890 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
328a0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 IENT ((sqlite3
328b0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
328c0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 )-1)../*.** CAPI
328d0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 3REF: Setting Th
328e0 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 e Result Of An S
328f0 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a QL Function.**.*
32900 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
32910 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
32920 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
32930 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
32940 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
32950 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
32960 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
32970 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
32980 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
32990 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
329a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
329b0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
329c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
329d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
329e0 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
329f0 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 much like the [p
32a00 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
32a10 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 ] family of.** f
32a20 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f unctions used to
32a30 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 bind values to
32a40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
32a50 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 in prepared stat
32a60 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 ements..** Refer
32a70 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 to the [SQL par
32a80 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 ameter] document
32a90 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
32aa0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
32ab0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
32ac0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
32ad0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
32ae0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
32af0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
32b00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
32b10 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 tion to be the B
32b20 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e LOB whose conten
32b30 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 t is pointed.**
32b40 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 to by the second
32b50 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 parameter and w
32b60 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 hich is N bytes
32b70 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 long where N is
32b80 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 the.** third par
32b90 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ameter..**.** ^T
32ba0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
32bb0 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 t_zeroblob() int
32bc0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 erfaces set the
32bd0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 result of.** the
32be0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
32bf0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
32c00 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 be a BLOB conta
32c10 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a ining all zero.*
32c20 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 * bytes and N by
32c30 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 tes in size, whe
32c40 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 re N is the valu
32c50 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 e of the 2nd par
32c60 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ameter..**.** ^T
32c70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
32c80 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 t_double() inter
32c90 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
32ca0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
32cb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
32cc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
32cd0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f be a floating po
32ce0 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 int value specif
32cf0 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e ied.** by its 2n
32d00 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
32d10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
32d20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e esult_error() an
32d30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32d40 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 _error16() funct
32d50 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 ions.** cause th
32d60 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 e implemented SQ
32d70 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 L function to th
32d80 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e row an exception
32d90 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 ..** ^SQLite use
32da0 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 s the string poi
32db0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a nted to by the.*
32dc0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * 2nd parameter
32dd0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c of sqlite3_resul
32de0 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c t_error() or sql
32df0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
32e00 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 r16().** as the
32e10 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 text of an error
32e20 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 message. ^SQLi
32e30 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 te interprets th
32e40 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
32e50 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 ge string from s
32e60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
32e70 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 ror() as UTF-8.
32e80 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 ^SQLite.** inter
32e90 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 prets the string
32ea0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
32eb0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 sult_error16() a
32ec0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 s UTF-16 in nati
32ed0 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 ve.** byte order
32ee0 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 . ^If the third
32ef0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
32f00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
32f10 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
32f20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
32f30 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 6() is negative
32f40 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
32f50 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a s as the error.*
32f60 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 * message all te
32f70 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 xt up through th
32f80 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 e first zero cha
32f90 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 racter..** ^If t
32fa0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
32fb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
32fc0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a sult_error() or.
32fd0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
32fe0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e t_error16() is n
32ff0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e on-negative then
33000 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 SQLite takes th
33010 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 at many.** bytes
33020 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 (not characters
33030 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 ) from the 2nd p
33040 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
33050 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
33060 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
33070 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e esult_error() an
33080 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
33090 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f _error16().** ro
330a0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 utines make a pr
330b0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
330c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
330d0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 text before.** t
330e0 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e hey return. Hen
330f0 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ce, the calling
33100 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 function can dea
33110 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f llocate or.** mo
33120 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 dify the text af
33130 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 ter they return
33140 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a without harm..**
33150 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
33160 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 sult_error_code(
33170 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 ) function chang
33180 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 es the error cod
33190 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
331a0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 SQLite as a res
331b0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 ult of an error
331c0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 in a function.
331d0 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 ^By default,.**
331e0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 the error code i
331f0 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 s SQLITE_ERROR.
33200 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 ^A subsequent c
33210 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 all to sqlite3_r
33220 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a esult_error().**
33230 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
33240 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 lt_error16() res
33250 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f ets the error co
33260 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 de to SQLITE_ERR
33270 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 OR..**.** ^The s
33280 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
33290 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 ror_toobig() int
332a0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 erface causes SQ
332b0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e Lite to throw an
332c0 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 .** error indica
332d0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 ting that a stri
332e0 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f ng or BLOB is to
332f0 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 o long to repres
33300 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
33310 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33320 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 rror_nomem() int
33330 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 erface causes SQ
33340 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e Lite to throw an
33350 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 .** error indica
33360 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f ting that a memo
33370 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
33380 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 iled..**.** ^The
33390 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
333a0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 int() interface
333b0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
333c0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
333d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
333e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
333f0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 be the 32-bit si
33400 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
33410 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 value given in t
33420 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e he 2nd argument.
33430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
33440 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 _result_int64()
33450 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
33460 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
33470 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
33480 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
33490 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
334a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
334b0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
334c0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
334d0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
334e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
334f0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
33500 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
33510 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
33520 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
33530 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
33540 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
33550 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
33560 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 3_result_text(),
33570 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33580 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c text16(),.** sql
33590 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
335a0 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 16le(), and sqli
335b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
335c0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6be() interfaces
335d0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 .** set the retu
335e0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
335f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33600 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
33610 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 be.** a text str
33620 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 ing which is rep
33630 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d resented as UTF-
33640 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 8, UTF-16 native
33650 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 byte order,.**
33660 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e UTF-16 little en
33670 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 dian, or UTF-16
33680 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 big endian, resp
33690 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 ectively..** ^SQ
336a0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 Lite takes the t
336b0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 ext result from
336c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
336d0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 from.** the 2nd
336e0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
336f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33700 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
33710 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 ..** ^If the 3rd
33720 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
33730 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
33740 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
33750 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 s.** is negative
33760 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 , then SQLite ta
33770 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 kes result text
33780 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
33790 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 ameter.** throug
337a0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
337b0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
337c0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
337d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
337e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
337f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
33800 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
33810 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
33820 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
33830 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
33840 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
33850 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
33860 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
33870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
33880 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
33890 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 ion result. If
338a0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
338b0 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 r is non-negativ
338c0 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 e, then it.** mu
338d0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
338e0 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 ffset into the s
338f0 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 tring where the
33900 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
33910 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 ould.** appear i
33920 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 f the string whe
33930 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 re NUL terminate
33940 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 d. If any NUL c
33950 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a haracters occur.
33960 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 ** in the string
33970 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 at a byte offse
33980 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 t that is less t
33990 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 han the value of
339a0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 the 3rd.** para
339b0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
339c0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
339d0 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d will contain em
339e0 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 bedded NULs and
339f0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 the.** result of
33a00 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 expressions ope
33a10 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 rating on string
33a20 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 s with embedded
33a30 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 NULs is undefine
33a40 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 d..** ^If the 4t
33a50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
33a60 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33a70 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
33a80 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
33a90 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
33aa0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
33ab0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
33ac0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 calls that.** fu
33ad0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 nction as the de
33ae0 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
33af0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
33b00 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a ult when it has.
33b10 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e ** finished usin
33b20 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
33b30 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
33b40 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
33b50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
33b60 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f xt* interfaces o
33b70 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
33b80 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
33b90 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
33ba0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
33bb0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
33bc0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
33bd0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
33be0 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
33bf0 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
33c00 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
33c10 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
33c20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f the parameter no
33c30 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
33c40 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 tor on the conte
33c50 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 nt.** when it ha
33c60 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
33c70 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
33c80 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
33c90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
33ca0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
33cb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
33cc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
33cd0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
33ce0 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
33cf0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
33d00 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
33d10 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
33d20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
33d30 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
33d40 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
33d50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
33d60 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
33d70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33d80 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
33d90 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
33da0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 ts the result of
33db0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
33dc0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
33dd0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 tion to be a cop
33de0 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 y the.** [unprot
33df0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
33e00 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 lue] object spec
33e10 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 ified by the 2nd
33e20 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 parameter. ^Th
33e30 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 e.** sqlite3_res
33e40 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 ult_value() inte
33e50 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f rface makes a co
33e60 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 py of the [sqlit
33e70 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 e3_value].** so
33e80 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 that the [sqlite
33e90 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 3_value] specifi
33ea0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 ed in the parame
33eb0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f ter may change o
33ec0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 r.** be dealloca
33ed0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
33ee0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
33ef0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 returns without
33f00 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 harm..** ^A [pr
33f10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
33f20 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 value] object ma
33f30 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 y always be used
33f40 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e where an.** [un
33f50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
33f60 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
33f70 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 is required, so
33f80 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f either.** kind o
33f90 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 f [sqlite3_value
33fa0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 ] object can be
33fb0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 used with this i
33fc0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
33fd0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 If these routine
33fe0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f s are called fro
33ff0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 m within the dif
34000 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a ferent thread.**
34010 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f than the one co
34020 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 ntaining the app
34030 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34040 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 function that r
34050 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b eceived.** the [
34060 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d sqlite3_context]
34070 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 pointer, the re
34080 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
34090 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c ned..*/.void sql
340a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
340b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
340c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
340d0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
340e0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
340f0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 e3_result_double
34100 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
34110 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 *, double);.void
34120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34130 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f error(sqlite3_co
34140 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
34150 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 ar*, int);.void
34160 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
34170 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 rror16(sqlite3_c
34180 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
34190 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 oid*, int);.void
341a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
341b0 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c error_toobig(sql
341c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
341d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
341e0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 ult_error_nomem(
341f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
34200 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
34210 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 result_error_cod
34220 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
34230 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 t*, int);.void s
34240 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
34250 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
34260 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 t*, int);.void s
34270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
34280 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 t64(sqlite3_cont
34290 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ext*, sqlite3_in
342a0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 t64);.void sqlit
342b0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 e3_result_null(s
342c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
342d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
342e0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 esult_text(sqlit
342f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
34300 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 st char*, int, v
34310 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
34320 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
34330 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ult_text16(sqlit
34340 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
34350 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 st void*, int, v
34360 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
34370 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
34380 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c ult_text16le(sql
34390 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
343a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
343b0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
343c0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
343d0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 sult_text16be(sq
343e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
343f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
34400 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
34410 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
34420 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 esult_value(sqli
34430 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
34440 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 lite3_value*);.v
34450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
34460 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 lt_zeroblob(sqli
34470 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
34480 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t n);../*.** CAP
34490 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 I3REF: Define Ne
344a0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 w Collating Sequ
344b0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ences.**.** ^The
344c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 se functions add
344d0 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 , remove, or mod
344e0 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e ify a [collation
344f0 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 ] associated.**
34500 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
34510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
34520 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 pecified as the
34530 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
34540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 **.** ^The name
34550 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e of the collation
34560 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
34570 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 ng.** for sqlite
34580 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
34590 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 on() and sqlite3
345a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
345b0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 n_v2().** and a
345c0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
345d0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
345e0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 er for sqlite3_c
345f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
34600 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6()..** ^Collati
34610 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f on names that co
34620 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f mpare equal acco
34630 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 rding to [sqlite
34640 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 3_strnicmp()] ar
34650 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 e.** considered
34660 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e to be the same n
34670 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ame..**.** ^(The
34680 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
34690 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 (eTextRep) must
346a0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f be one of the co
346b0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e nstants:.** <ul>
346c0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
346d0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _UTF8],.** <li>
346e0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
346f0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
34700 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c E_UTF16BE],.** <
34710 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
34720 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 6], or.** <li> [
34730 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
34740 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 GNED]..** </ul>)
34750 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 ^.** ^The eTextR
34760 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 ep argument dete
34770 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 rmines the encod
34780 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 ing of strings p
34790 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 assed.** to the
347a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
347b0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 on callback, xCa
347c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 llback..** ^The
347d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 [SQLITE_UTF16] a
347e0 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 nd [SQLITE_UTF16
347f0 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 _ALIGNED] values
34800 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a for eTextRep.**
34810 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 force strings t
34820 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 o be UTF16 with
34830 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
34840 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 r..** ^The [SQLI
34850 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
34860 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 ] value for eTex
34870 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 tRep forces stri
34880 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 ngs to begin.**
34890 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 on an even byte
348a0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e address..**.** ^
348b0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d The fourth argum
348c0 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e ent, pArg, is an
348d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
348e0 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 a pointer that i
348f0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f s passed.** thro
34900 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 ugh as the first
34910 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
34920 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
34930 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ion callback..**
34940 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 .** ^The fifth a
34950 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 rgument, xCallba
34960 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ck, is a pointer
34970 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e to the collatin
34980 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e g function..** ^
34990 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 Multiple collati
349a0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e ng functions can
349b0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 be registered u
349c0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 sing the same na
349d0 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 me but.** with d
349e0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 ifferent eTextRe
349f0 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 p parameters and
34a00 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
34a10 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 whichever.** fu
34a20 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
34a30 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
34a40 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f of data transfo
34a50 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 rmation..** ^If
34a60 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 the xCallback ar
34a70 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 gument is NULL t
34a80 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e hen the collatin
34a90 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a g function is.**
34aa0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e deleted. ^When
34ab0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 all collating f
34ac0 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 unctions having
34ad0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 the same name ar
34ae0 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 e deleted,.** th
34af0 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 at collation is
34b00 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 no longer usable
34b10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c ..**.** ^The col
34b20 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
34b30 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
34b40 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 ked with a copy
34b50 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 of the pArg .**
34b60 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
34b70 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 pointer and wit
34b80 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e h two strings in
34b90 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 the encoding sp
34ba0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
34bb0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d e eTextRep argum
34bc0 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 ent. The collat
34bd0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 ing function mus
34be0 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 t return an.** i
34bf0 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e nteger that is n
34c00 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f egative, zero, o
34c10 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 r positive.** if
34c20 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e the first strin
34c30 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 g is less than,
34c40 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 equal to, or gre
34c50 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 ater than the se
34c60 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 cond,.** respect
34c70 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 ively. A collat
34c80 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 ing function mus
34c90 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 t always return
34ca0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a the same answer.
34cb0 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d ** given the sam
34cc0 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 e inputs. If tw
34cd0 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 o or more collat
34ce0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ing functions ar
34cf0 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 e registered.**
34d00 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c to the same coll
34d10 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e ation name (usin
34d20 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 g different eTex
34d30 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 tRep values) the
34d40 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 n all.** must gi
34d50 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 ve an equivalent
34d60 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 answer when inv
34d70 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 oked with equiva
34d80 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a lent strings..**
34d90 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
34da0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 unction must obe
34db0 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 y the following
34dc0 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 properties for a
34dd0 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c ll.** strings A,
34de0 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a B, and C:.**.**
34df0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 <ol>.** <li> If
34e00 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e A==B then B==A.
34e10 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
34e20 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 and B==C then A
34e30 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 ==C..** <li> If
34e40 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 A<B THEN B>
34e50 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 ;A..** <li> If A
34e60 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 <B and B<C
34e70 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a then A<C..**
34e80 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </ol>.**.** If
34e90 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 a collating func
34ea0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f tion fails any o
34eb0 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 f the above cons
34ec0 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 traints and that
34ed0 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 .** collating fu
34ee0 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 nction is regis
34ef0 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 tered and used,
34f00 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
34f10 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 r of SQLite.** i
34f20 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
34f30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34f40 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
34f50 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 _v2() works like
34f60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
34f70 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 collation().** w
34f80 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e ith the addition
34f90 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 that the xDestr
34fa0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 oy callback is i
34fb0 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 nvoked on pArg w
34fc0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 hen.** the colla
34fd0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
34fe0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f deleted..** ^Co
34ff0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
35000 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 s are deleted wh
35010 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 en they are over
35020 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a ridden by later.
35030 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 ** calls to the
35040 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 collation creati
35050 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 on functions or
35060 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 when the.** [dat
35070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
35080 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e ] is closed usin
35090 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
350a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ()]..**.** ^The
350b0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 xDestroy callbac
350c0 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 k is <u>not</u>
350d0 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a called if the .*
350e0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
350f0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
35100 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 function fails.
35110 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
35120 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c at invoke.** sql
35130 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
35140 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 ation_v2() with
35150 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 a non-NULL xDest
35160 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f roy argument sho
35170 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 uld .** check th
35180 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e e return code an
35190 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 d dispose of the
351a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
351b0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 a pointer.** the
351c0 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 mselves rather t
351d0 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 han expecting SQ
351e0 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 Lite to deal wit
351f0 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a h it for them..*
35200 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 * This is differ
35210 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f ent from every o
35220 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
35230 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f rface. The inco
35240 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 nsistency .** is
35250 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 unfortunate but
35260 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 cannot be chang
35270 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
35280 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a ing backwards .*
35290 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e * compatibility.
352a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
352b0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 [sqlite3_colla
352c0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 tion_needed()] a
352d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c nd [sqlite3_coll
352e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
352f0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
35300 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
35310 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 on(. sqlite3*,
35320 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
35330 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 Name, . int eTe
35340 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a xtRep, . void *
35350 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f pArg,. int(*xCo
35360 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
35370 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
35380 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
35390 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
353a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
353b0 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
353c0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
353d0 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 me, . int eText
353e0 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 Rep, . void *pA
353f0 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 rg,. int(*xComp
35400 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 are)(void*,int,c
35410 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 onst void*,int,c
35420 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 onst void*),. v
35430 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 oid(*xDestroy)(v
35440 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c oid*).);.int sql
35450 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
35460 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 ation16(. sqlit
35470 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f e3*, . const vo
35480 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 id *zName,. int
35490 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
354a0 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 id *pArg,. int(
354b0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
354c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
354d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
354e0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ).);../*.** CAPI
354f0 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 3REF: Collation
35500 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 Needed Callbacks
35510 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 .**.** ^To avoid
35520 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 having to regis
35530 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f ter all collatio
35540 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f n sequences befo
35550 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a re a database.**
35560 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 can be used, a
35570 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 single callback
35580 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 function may be
35590 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 registered with
355a0 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
355b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 connection] to
355c0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 be invoked whene
355d0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 ver an undefined
355e0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 collation.** se
355f0 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 quence is requir
35600 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
35610 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 e function is re
35620 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 gistered using t
35630 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 he sqlite3_colla
35640 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 tion_needed() AP
35650 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 I,.** then it is
35660 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 passed the name
35670 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 s of undefined c
35680 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 ollation sequenc
35690 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a es as strings.**
356a0 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d encoded in UTF-
356b0 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 8. ^If sqlite3_c
356c0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 ollation_needed1
356d0 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 6() is used,.**
356e0 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 the names are pa
356f0 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 ssed as UTF-16 i
35700 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 n machine native
35710 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 byte order..**
35720 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 ^A call to eithe
35730 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 r function repla
35740 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 ces the existing
35750 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 collation-neede
35760 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a d callback..**.*
35770 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c * ^(When the cal
35780 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
35790 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 , the first argu
357a0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 ment passed is a
357b0 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 copy.** of the
357c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
357d0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 to sqlite3_colla
357e0 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 tion_needed() or
357f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c .** sqlite3_coll
35800 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
35810 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . The second ar
35820 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 gument is the da
35830 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
35840 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 tion. The third
35850 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 argument is one
35860 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 of [SQLITE_UTF8
35870 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 ], [SQLITE_UTF16
35880 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 BE],.** or [SQLI
35890 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 TE_UTF16LE], ind
358a0 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 icating the most
358b0 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 desirable form
358c0 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e of the collation
358d0 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e .** sequence fun
358e0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 ction required.
358f0 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
35900 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
35910 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 e of the.** requ
35920 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 ired collation s
35930 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a equence.)^.**.**
35940 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 The callback fu
35950 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 nction should re
35960 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 gister the desir
35970 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 ed collation usi
35980 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ng.** [sqlite3_c
35990 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
359a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
359b0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 ate_collation16(
359c0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
359d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
359e0 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e ion_v2()]..*/.in
359f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 t sqlite3_collat
35a00 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 ion_needed(. sq
35a10 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a lite3*, . void*
35a20 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 , . void(*)(voi
35a30 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
35a40 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 eTextRep,const c
35a50 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c har*).);.int sql
35a60 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
35a70 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 eeded16(. sqlit
35a80 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 e3*, . void*,.
35a90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
35aa0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
35ab0 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a tRep,const void*
35ac0 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c ).);..#ifdef SQL
35ad0 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a ITE_HAS_CODEC./*
35ae0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 .** Specify the
35af0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 key for an encry
35b00 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 pted database.
35b10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f This routine sho
35b20 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 uld be.** called
35b30 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c right after sql
35b40 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a ite3_open()..**.
35b50 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 ** The code to i
35b60 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 mplement this AP
35b70 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 I is not availab
35b80 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 le in the public
35b90 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 release.** of S
35ba0 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 QLite..*/.int sq
35bb0 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c lite3_key(. sql
35bc0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
35bd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
35be0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
35bf0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
35c00 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
35c10 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
35c20 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a key */.);../*.*
35c30 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 * Change the key
35c40 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 on an open data
35c50 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 base. If the cu
35c60 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 rrent database i
35c70 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 s not.** encrypt
35c80 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 ed, this routine
35c90 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 will encrypt it
35ca0 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 . If pNew==0 or
35cb0 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a nNew==0, the.**
35cc0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 database is dec
35cd0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 rypted..**.** Th
35ce0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d e code to implem
35cf0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 ent this API is
35d00 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e not available in
35d10 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 the public rele
35d20 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ase.** of SQLite
35d30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
35d40 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 _rekey(. sqlite
35d50 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
35d60 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
35d70 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
35d80 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
35d90 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
35da0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 ey /* The ne
35db0 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a w key */.);../*.
35dc0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 ** Specify the a
35dd0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f ctivation key fo
35de0 72 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 r a SEE database
35df0 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 . Unless .** ac
35e00 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 tivated, none of
35e10 20 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 the SEE routine
35e20 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a s will work..*/.
35e30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 void sqlite3_act
35e40 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e ivate_see(. con
35e50 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 st char *zPassPh
35e60 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 rase /* A
35e70 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 ctivation phrase
35e80 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 */.);.#endif..#
35e90 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 ifdef SQLITE_ENA
35ea0 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 BLE_CEROD./*.**
35eb0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 Specify the acti
35ec0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 vation key for a
35ed0 20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e CEROD database.
35ee0 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 Unless .** act
35ef0 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 ivated, none of
35f00 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e the CEROD routin
35f10 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f es will work..*/
35f20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 .void sqlite3_ac
35f30 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 tivate_cerod(.
35f40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 const char *zPas
35f50 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f sPhrase /
35f60 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 * Activation phr
35f70 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 ase */.);.#endif
35f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35f90 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 : Suspend Execut
35fa0 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 ion For A Short
35fb0 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 Time.**.** The s
35fc0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 qlite3_sleep() f
35fd0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 unction causes t
35fe0 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 he current threa
35ff0 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 d to suspend exe
36000 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 cution.** for at
36010 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 least a number
36020 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 of milliseconds
36030 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 specified in its
36040 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
36050 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 * If the operati
36060 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e ng system does n
36070 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 ot support sleep
36080 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a requests with.*
36090 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 * millisecond ti
360a0 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 me resolution, t
360b0 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c hen the time wil
360c0 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 l be rounded up
360d0 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 to.** the neares
360e0 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 t second. The nu
360f0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
36100 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 onds of sleep ac
36110 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 tually.** reques
36120 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 ted from the ope
36130 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 rating system is
36140 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
36150 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 ^SQLite impleme
36160 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 nts this interfa
36170 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 ce by calling th
36180 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 e xSleep().** me
36190 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 thod of the defa
361a0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
361b0 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 ] object. If th
361c0 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f e xSleep() metho
361d0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 d.** of the defa
361e0 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 ult VFS is not i
361f0 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 mplemented corre
36200 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 ctly, or not imp
36210 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 lemented at.** a
36220 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ll, then the beh
36230 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 avior of sqlite3
36240 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 _sleep() may dev
36250 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 iate from the de
36260 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 scription.** in
36270 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 the previous par
36280 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 agraphs..*/.int
36290 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e sqlite3_sleep(in
362a0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
362b0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 REF: Name Of The
362c0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 Folder Holding
362d0 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a Temporary Files.
362e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 **.** ^(If this
362f0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 global variable
36300 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
36310 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 to a string whi
36320 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d ch is.** the nam
36330 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 e of a folder (a
36340 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 .k.a. directory)
36350 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f , then all tempo
36360 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 rary files.** cr
36370 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 eated by SQLite
36380 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 when using a bui
36390 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 lt-in [sqlite3_v
363a0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c fs | VFS].** wil
363b0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 l be placed in t
363c0 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e hat directory.)^
363d0 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 ^If this varia
363e0 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c ble.** is a NULL
363f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 pointer, then S
36400 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 QLite performs a
36410 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 search for an a
36420 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 ppropriate.** te
36430 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 mporary file dir
36440 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 ectory..**.** It
36450 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
36460 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
36470 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 his variable in
36480 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a more than one.**
36490 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d thread at a tim
364a0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 e. It is not sa
364b0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f fe to read or mo
364c0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
364d0 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 le.** if a [data
364e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
364f0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 is being used a
36500 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
36510 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a in a separate.**
36520 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 thread..** It i
36530 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 s intended that
36540 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 this variable be
36550 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 set once.** as
36560 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 part of process
36570 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 initialization a
36580 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 nd before any SQ
36590 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a Lite interface.*
365a0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 * routines have
365b0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 been called and
365c0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
365d0 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e le remain unchan
365e0 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 ged.** thereafte
365f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 r..**.** ^The [t
36600 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
36610 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 ory pragma] may
36620 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 modify this vari
36630 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a able and cause.*
36640 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f * it to point to
36650 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
36660 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
36670 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 alloc]. ^Furthe
36680 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 rmore,.** the [t
36690 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
366a0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 ory pragma] alwa
366b0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 ys assumes that
366c0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 any string.** th
366d0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
366e0 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 points to is he
366f0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 ld in memory obt
36700 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b ained from .** [
36710 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 sqlite3_malloc]
36720 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d and the pragma m
36730 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 ay attempt to fr
36740 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a ee that memory.*
36750 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
36760 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 _free]..** Hence
36770 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 , if this variab
36780 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 le is modified d
36790 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 irectly, either
367a0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 it should be.**
367b0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 made NULL or mad
367c0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 e to point to me
367d0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
367e0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
367f0 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 oc].** or else t
36800 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 he use of the [t
36810 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
36820 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 ory pragma] shou
36830 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a ld be avoided..*
36840 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
36850 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 Windows Runtime
36860 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
36870 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 temporary direct
36880 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a ory must be set.
36890 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c ** prior to call
368a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 ing [sqlite3_ope
368b0 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f n] or [sqlite3_o
368c0 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 pen_v2]. Otherw
368d0 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ise, various.**
368e0 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 features that re
368f0 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 quire the use of
36900 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 temporary files
36910 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 may fail. Here
36920 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c is an.** exampl
36930 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 e of how to do t
36940 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 his using C++ wi
36950 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 th the Windows R
36960 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 untime:.**.** <b
36970 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
36980 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 ** LPCWSTR zPath
36990 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 = Windows::Stor
369a0 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e age::Application
369b0 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a Data::Current->.
369c0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 ** Te
369d0 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 mporaryFolder->P
369e0 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 ath->Data();.**
369f0 63 68 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 char zPathBuf	
36a00 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 1;MAX_PATH + 1&#
36a10 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 93;;.** memset(z
36a20 50 61 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 PathBuf, 0, size
36a30 6f 66 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a of(zPathBuf));.*
36a40 2a 20 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 * WideCharToMult
36a50 69 42 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 iByte(CP_UTF8, 0
36a60 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 , zPath, -1, zPa
36a70 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 thBuf, sizeof(zP
36a80 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 athBuf),.** &nbs
36a90 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c p; NULL, NUL
36aa0 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 L);.** sqlite3_t
36ab0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 emp_directory =
36ac0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
36ad0 22 25 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b "%s", zPathBuf);
36ae0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
36af0 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 kquote>.*/.SQLIT
36b00 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 E_EXTERN char *s
36b10 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
36b20 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ctory;../*.** CA
36b30 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
36b40 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
36b50 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 ng Database File
36b60 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 s.**.** ^(If thi
36b70 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c s global variabl
36b80 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 e is made to poi
36b90 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 nt to a string w
36ba0 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e hich is.** the n
36bb0 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 ame of a folder
36bc0 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 (a.k.a. director
36bd0 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 y), then all dat
36be0 61 62 61 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 abase files.** s
36bf0 70 65 63 69 66 69 65 64 20 77 69 74 68 20 61 20 pecified with a
36c00 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d relative pathnam
36c10 65 20 61 6e 64 20 63 72 65 61 74 65 64 20 6f 72 e and created or
36c20 20 61 63 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 accessed by.**
36c30 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e SQLite when usin
36c40 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e g a built-in win
36c50 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 dows [sqlite3_vf
36c60 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 s | VFS] will be
36c70 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 assumed.** to b
36c80 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 e relative to th
36c90 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 at directory.)^
36ca0 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c ^If this variabl
36cb0 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 e is a NULL.** p
36cc0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
36cd0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 ite assumes that
36ce0 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 all database fi
36cf0 6c 65 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a les specified.**
36d00 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 with a relative
36d10 20 70 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65 pathname are re
36d20 6c 61 74 69 76 65 20 74 6f 20 74 68 65 20 63 75 lative to the cu
36d30 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a rrent directory.
36d40 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65 ** for the proce
36d50 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 ss. Only the wi
36d60 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b 65 73 20 ndows VFS makes
36d70 75 73 65 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 use of this glob
36d80 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 al.** variable;
36d90 69 74 20 69 73 20 69 67 6e 6f 72 65 64 20 62 79 it is ignored by
36da0 20 74 68 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a the unix VFS..*
36db0 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 *.** Changing th
36dc0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 e value of this
36dd0 76 61 72 69 61 62 6c 65 20 77 68 69 6c 65 20 61 variable while a
36de0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
36df0 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 tion is.** open
36e00 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 61 20 can result in a
36e10 63 6f 72 72 75 70 74 20 64 61 74 61 62 61 73 65 corrupt database
36e20 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ..**.** It is no
36e30 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
36e40 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
36e50 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 riable in more t
36e60 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 han one.** threa
36e70 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 d at a time. It
36e80 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
36e90 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
36ea0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
36eb0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 if a [database c
36ec0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
36ed0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 ing used at the
36ee0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 same time in a s
36ef0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 eparate.** threa
36f00 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 d..** It is inte
36f10 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 nded that this v
36f20 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f ariable be set o
36f30 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f nce.** as part o
36f40 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 f process initia
36f50 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 lization and bef
36f60 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 ore any SQLite i
36f70 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 nterface.** rout
36f80 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 ines have been c
36f90 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 alled and that t
36fa0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d his variable rem
36fb0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a ain unchanged.**
36fc0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a thereafter..**.
36fd0 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 ** ^The [data_st
36fe0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
36ff0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
37000 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
37010 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
37020 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
37030 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
37040 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
37050 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c . ^Furthermore,
37060 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 5f 73 74 .** the [data_st
37070 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
37080 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 agma] always ass
37090 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 umes that any st
370a0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 ring.** that thi
370b0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 s variable point
370c0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 s to is held in
370d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
370e0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
370f0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 3_malloc] and th
37100 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 e pragma may att
37110 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 empt to free tha
37120 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e t memory.** usin
37130 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d g [sqlite3_free]
37140 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 ..** Hence, if t
37150 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
37160 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c modified directl
37170 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f y, either it sho
37180 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e uld be.** made N
37190 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 ULL or made to p
371a0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
371b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
371c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a lite3_malloc].**
371d0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 or else the use
371e0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 5f 73 74 of the [data_st
371f0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
37200 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 agma] should be
37210 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 avoided..*/.SQLI
37220 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a TE_EXTERN char *
37230 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69 72 sqlite3_data_dir
37240 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ectory;../*.** C
37250 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f API3REF: Test Fo
37260 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f r Auto-Commit Mo
37270 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 de.** KEYWORDS:
37280 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 {autocommit mode
37290 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c }.**.** ^The sql
372a0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d ite3_get_autocom
372b0 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 mit() interface
372c0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
372d0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 or.** zero if t
372e0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 he given databas
372f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
37300 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 or is not in aut
37310 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a ocommit mode,.**
37320 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 respectively.
37330 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 ^Autocommit mode
37340 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c is on by defaul
37350 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 t..** ^Autocommi
37360 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c t mode is disabl
37370 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 ed by a [BEGIN]
37380 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 statement..** ^A
37390 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 utocommit mode i
373a0 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 s re-enabled by
373b0 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 a [COMMIT] or [R
373c0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 OLLBACK]..**.**
373d0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 If certain kinds
373e0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 of errors occur
373f0 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 on a statement
37400 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 within a multi-s
37410 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e tatement.** tran
37420 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 saction (errors
37430 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 including [SQLIT
37440 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 E_FULL], [SQLITE
37450 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c _IOERR],.** [SQL
37460 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c ITE_NOMEM], [SQL
37470 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b ITE_BUSY], and [
37480 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
37490 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 ]) then the.** t
374a0 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 ransaction might
374b0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 be rolled back
374c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
374d0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a The only way to.
374e0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 ** find out whet
374f0 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d her SQLite autom
37500 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
37510 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 back the transac
37520 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e tion after.** an
37530 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 error is to use
37540 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a this function..
37550 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 **.** If another
37560 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 thread changes
37570 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 the autocommit s
37580 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 tatus of the dat
37590 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
375a0 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 ion while this r
375b0 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e outine is runnin
375c0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 g, then the retu
375d0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 rn value.** is u
375e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 ndefined..*/.int
375f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
37600 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a ocommit(sqlite3*
37610 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
37620 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 EF: Find The Dat
37630 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 abase Handle Of
37640 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
37650 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ment.**.** ^The
37660 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
37670 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 e interface retu
37680 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 rns the [databas
37690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
376a0 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 ndle.** to which
376b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
376c0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e tement] belongs.
376d0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 ^The [database
376e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 connection].**
376f0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
37700 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 te3_db_handle is
37710 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 the same [datab
37720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
37730 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 ** that was the
37740 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a first argument.*
37750 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
37760 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
37770 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 call (or its var
37780 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 iants) that was
37790 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 used to.** creat
377a0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 e the statement
377b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 in the first pla
377c0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a ce..*/.sqlite3 *
377d0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c sqlite3_db_handl
377e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 e(sqlite3_stmt*)
377f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
37800 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46 69 F: Return The Fi
37810 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61 74 lename For A Dat
37820 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
37830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37840 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 te3_db_filename(
37850 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 D,N) interface r
37860 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
37870 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a to a filename.*
37880 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
37890 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66 20 h database N of
378a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e connection D. ^
378b0 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 The main databas
378c0 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 e file.** has th
378d0 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 e name "main".
378e0 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 61 If there is no a
378f0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
37900 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 N on the databa
37910 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
37920 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62 61 D, or if databa
37930 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 se N is a tempor
37940 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 ary or in-memory
37950 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e 0a database, then.
37960 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
37970 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
37980 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 *.** ^The filena
37990 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 me returned by t
379a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 his function is
379b0 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74 68 the output of th
379c0 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 e.** xFullPathna
379d0 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 me method of the
379e0 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 [VFS]. ^In oth
379f0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66 69 er words, the fi
37a00 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 lename.** will b
37a10 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 e an absolute pa
37a20 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 thname, even if
37a30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 the filename use
37a40 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 d.** to open the
37a50 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69 6e database origin
37a60 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20 6f ally was a URI o
37a70 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e r relative pathn
37a80 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ame..*/.const ch
37a90 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 ar *sqlite3_db_f
37aa0 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 ilename(sqlite3
37ab0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 *db, const char
37ac0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a *zDbName);../*.*
37ad0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
37ae0 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74 61 62 rmine if a datab
37af0 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 ase is read-only
37b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37b10 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 te3_db_readonly(
37b20 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 D,N) interface r
37b30 65 74 75 72 6e 73 20 31 20 69 66 20 74 68 65 20 eturns 1 if the
37b40 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 database N.** of
37b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 connection D is
37b60 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 read-only, 0 if
37b70 20 69 74 20 69 73 20 72 65 61 64 2f 77 72 69 74 it is read/writ
37b80 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 e, or -1 if N is
37b90 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 not.** the name
37ba0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 6f of a database o
37bb0 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a n connection D..
37bc0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 */.int sqlite3_d
37bd0 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 b_readonly(sqlit
37be0 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 e3 *db, const ch
37bf0 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f ar *zDbName);../
37c00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
37c10 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 ind the next pre
37c20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
37c30 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
37c40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
37c50 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e pointer to the n
37c60 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 ext [prepared st
37c70 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a atement] after.*
37c80 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 * pStmt associat
37c90 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
37ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
37cb0 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d ] pDb. ^If pStm
37cc0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 t is NULL.** the
37cd0 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 n this interface
37ce0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
37cf0 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 er to the first
37d00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37d10 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 nt.** associated
37d20 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 with the databa
37d30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 se connection pD
37d40 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 b. ^If no prepa
37d50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
37d60 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 satisfies the c
37d70 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 onditions of thi
37d80 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 s routine, it re
37d90 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a turns NULL..**.*
37da0 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 * The [database
37db0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e connection] poin
37dc0 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 ter D in a call
37dd0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e to.** [sqlite3_n
37de0 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d ext_stmt(D,S)] m
37df0 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 ust refer to an
37e00 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a open database.**
37e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 connection and
37e20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 in particular mu
37e30 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c st not be a NULL
37e40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c pointer..*/.sql
37e50 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 ite3_stmt *sqlit
37e60 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c e3_next_stmt(sql
37e70 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 ite3 *pDb, sqlit
37e80 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
37e90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
37ea0 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c : Commit And Rol
37eb0 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 lback Notificati
37ec0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a on Callbacks.**.
37ed0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37ee0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e commit_hook() in
37ef0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 terface register
37f00 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 s a callback.**
37f10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 function to be i
37f20 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
37f30 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 a transaction is
37f40 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 [COMMIT | commi
37f50 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 tted]..** ^Any c
37f60 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 allback set by a
37f70 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
37f80 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 o sqlite3_commit
37f90 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 _hook().** for t
37fa0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
37fb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
37fc0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 verridden..** ^T
37fd0 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 he sqlite3_rollb
37fe0 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 ack_hook() inter
37ff0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
38000 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
38010 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f ction to be invo
38020 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 ked whenever a t
38030 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 ransaction is [R
38040 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 OLLBACK | rolled
38050 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 back]..** ^Any
38060 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 callback set by
38070 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 a previous call
38080 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 to sqlite3_rollb
38090 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f ack_hook().** fo
380a0 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 r the same datab
380b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
380c0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a s overridden..**
380d0 20 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d ^The pArg argum
380e0 65 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 ent is passed th
380f0 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c rough to the cal
38100 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 lback..** ^If th
38110 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 e callback on a
38120 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 commit hook func
38130 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e tion returns non
38140 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 -zero,.** then t
38150 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e he commit is con
38160 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f verted into a ro
38170 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 llback..**.** ^T
38180 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 he sqlite3_commi
38190 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e t_hook(D,C,P) an
381a0 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 d sqlite3_rollba
381b0 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 ck_hook(D,C,P) f
381c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 unctions.** retu
381d0 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e rn the P argumen
381e0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 t from the previ
381f0 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 ous call of the
38200 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a same function.**
38210 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 on the same [da
38220 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
38230 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f n] D, or NULL fo
38240 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 r.** the first c
38250 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e all for each fun
38260 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a ction on D..**.*
38270 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 * The commit and
38280 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 rollback hook c
38290 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 allbacks are not
382a0 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 reentrant..** T
382b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c he callback impl
382c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 ementation must
382d0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 not do anything
382e0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 that will modify
382f0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
38300 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
38310 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61 6c invoked the cal
38320 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 lback. Any acti
38330 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 ons.** to modify
38340 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
38350 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 nnection must be
38360 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 deferred until
38370 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d after the.** com
38380 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b pletion of the [
38390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
383a0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
383b0 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a red the commit.*
383c0 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f * or rollback ho
383d0 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ok in the first
383e0 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 place..** Note t
383f0 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 hat running any
38400 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74 65 6d other SQL statem
38410 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ents, including
38420 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
38430 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 s,.** or merely
38440 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
38450 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
38460 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
38470 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a ()] will modify.
38480 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
38490 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 connections for
384a0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 the meaning of "
384b0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 modify" in this
384c0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a paragraph..**.**
384d0 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 ^Registering a
384e0 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 NULL function di
384f0 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 sables the callb
38500 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e ack..**.** ^When
38510 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b the commit hook
38520 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e callback routin
38530 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 e returns zero,
38540 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 the [COMMIT].**
38550 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c operation is all
38560 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 owed to continue
38570 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 normally. ^If
38580 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a the commit hook.
38590 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ** returns non-z
385a0 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 ero, then the [C
385b0 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 OMMIT] is conver
385c0 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c ted into a [ROLL
385d0 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 BACK]..** ^The r
385e0 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 ollback hook is
385f0 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c invoked on a rol
38600 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c lback that resul
38610 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 ts from a commit
38620 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 .** hook returni
38630 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 ng non-zero, jus
38640 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 t as it would be
38650 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 with any other
38660 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 rollback..**.**
38670 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 ^For the purpose
38680 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 s of this API, a
38690 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 transaction is
386a0 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 said to have bee
386b0 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b n.** rolled back
386c0 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 if an explicit
386d0 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 "ROLLBACK" state
386e0 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 ment is executed
386f0 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 , or.** an error
38700 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 or constraint c
38710 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 auses an implici
38720 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 t rollback to oc
38730 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c cur..** ^The rol
38740 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 lback callback i
38750 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 s not invoked if
38760 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
38770 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c s.** automatical
38780 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 ly rolled back b
38790 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 ecause the datab
387a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
387b0 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
387c0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 See also the [sq
387d0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f lite3_update_hoo
387e0 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a k()] interface..
387f0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
38800 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c _commit_hook(sql
38810 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f ite3*, int(*)(vo
38820 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f id*), void*);.vo
38830 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c id *sqlite3_roll
38840 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 back_hook(sqlite
38850 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 3*, void(*)(void
38860 20 2a 29 2c 20 76