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 74 68 ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 d by.** the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 3_exec(. sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 3*,
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 /* An open
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f database */. co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 nst 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 20 20 20 20 2f 2a 20 53 51 4c 20 /* SQL
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 */. int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 har**,char**),
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a tion */. void *
4090: 2c 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 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 */. char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 msg
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 integer result
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 t shown.** here
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 cate success or
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 ine SQLITE_OK
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 0 /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 -of-error-codes
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 E_ERROR 1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 /* SQL error
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 QLITE_INTERNAL
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 2 /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 ine SQLITE_PERM
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 3 /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 ne SQLITE_ABORT
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 4 /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 ITE_BUSY
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 5 /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 QLITE_LOCKED
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 6 /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f MEM 7 /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 QLITE_READONLY
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 8 /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 _INTERRUPT 9
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 E_IOERR 10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 /* Some kind
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a RUPT 11 /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 12 /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ol() */.#define
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 SQLITE_FULL
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 13 /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 use database is
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 full */.#define
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 SQLITE_CANTOPEN
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 14 /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f OTOCOL 15 /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 * Database lock
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 _EMPTY 16
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 e SQLITE_SCHEMA
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 17 /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 G 18 /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 TE_CONSTRAINT 1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 9 /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 TCH 20 /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 ITE_MISUSE
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 21 /* Library
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 TE_NOLFS 2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 2 /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 AUTH 23
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 T 24 /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 _RANGE 25
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 nd out of range
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 E_NOTADB 26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 d that is not a
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 NOTICE 27
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 og() */.#define
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 SQLITE_WARNING
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 28 /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 e SQLITE_ROW
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 100 /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 ite3_step() has
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 ITE_DONE
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 101 /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 codes}.**.** In
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 eturn one of 26
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c odes]. However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 experience has
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 shown that many
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 like. In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 sult codes that
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 s. The extended
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63 t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69 rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 me. Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 QLITE_OK result
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 code will never
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 be extended. It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 will always.**
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 TE_IOERR_READ
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 AD (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 _IOERR_WRITE
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 IOERR_FSYNC
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 OERR_DIR_FSYNC
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 ERR_TRUNCATE
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 RR_FSTAT
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 R_UNLOCK
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 _RDLOCK
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 DELETE
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 BLOCKED
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 NOMEM
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 ACCESS
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 K (SQLITE_IOERR
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 CLOSE
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 DIR_CLOSE
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 SHMOPEN
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 SHMSIZE
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 SHMLOCK
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 SHMMAP
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 SEEK
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 DELETE_NOENT
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 MMAP
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 GETTEMPPATH
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 CONVPATH
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 _SHAREDCACHE
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 | (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 RECOVERY
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 (SQLITE_BUSY
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 | (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 _SNAPSHOT
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 | (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 TOPEN_NOTEMPDIR
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 ANTOPEN_ISDIR
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 TH (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 PATH (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 B (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 ECOVERY (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 _CANTLOCK
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 LY_ROLLBACK
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 ONLY_DBMOVED
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 ORT_ROLLBACK
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 STRAINT_CHECK
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 ITHOOK (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 FOREIGNKEY (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 INT_FUNCTION
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 STRAINT_NOTNULL
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 ARYKEY (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 TRIGGER (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 INT_UNIQUE
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 STRAINT_VTAB
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 D (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 VER_WAL (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 OINDEX (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 v2()] interface
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 _OPEN_READONLY
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 1 /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 2 /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 _OPEN_CREATE
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 4 /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 OSE 0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 8 /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 _OPEN_EXCLUSIVE
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 _OPEN_AUTOPROXY
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 _OPEN_URI
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 _OPEN_MEMORY
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 _OPEN_MAIN_DB
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 _OPEN_TEMP_DB
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 DB 0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 AL 0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 AL 0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 RNAL 0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 _OPEN_NOMUTEX
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 _OPEN_FULLMUTEX
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 E 0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 HE 0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 0 /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 _OPEN_WAL
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 0 /* VFS only *
6390: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 /../* Reserved:
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
63b0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 0x00F000
63c0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 00 */../*.** CAP
63d0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 I3REF: Device Ch
63e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a aracteristics.**
63f0: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 .** The xDeviceC
6400: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d haracteristics m
6410: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 ethod of the [sq
6420: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6430: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 ].** object retu
6440: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 rns an integer w
6450: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 hich is a vector
6460: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 of these.** bit
6470: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 values expressi
6480: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 ng I/O character
6490: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 istics of the ma
64a0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 ss storage.** de
64b0: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 vice that holds
64c0: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 the file that th
64d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
64e0: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 thods].** refers
64f0: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 to..**.** The S
6500: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6510: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e IC property mean
6520: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 s that all write
6530: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 s of.** any size
6540: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a TOMICnnn values.
6570: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 ** mean that wri
6580: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 tes of blocks th
6590: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 at are nnn bytes
65a0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 in size and.**
65b0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 are aligned to a
65c0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 n address which
65d0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 is an integer mu
65e0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e ltiple of.** nnn
65f0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
6600: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
6610: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 AFE_APPEND value
6620: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 means.** that w
6630: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 hen data is appe
6640: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 nded to a file,
6650: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 the data is appe
6660: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 nded.** first th
6670: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 en the size of t
6680: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e he file is exten
6690: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f ded, never the o
66a0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 ther.** way arou
66b0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f nd. The SQLITE_
66c0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
66d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
66e0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 that.** informat
66f0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 ion is written t
6700: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 o disk in the sa
6710: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c me order as call
6720: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 s.** to xWrite()
6730: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6740: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 CAP_POWERSAFE_OV
6750: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 ERWRITE property
6760: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 means that.** a
6770: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c fter reboot foll
6780: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 owing a crash or
6790: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 power loss, the
67a0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 only bytes in a
67b0: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 .** file that we
67c0: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 re written at th
67d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 e application le
67e0: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 vel might have c
67f0: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 hanged.** and th
6800: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 at adjacent byte
6810: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 s, even bytes wi
6820: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 thin the same se
6830: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 ctor are.** guar
6840: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 anteed to be unc
6850: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c hanged. The SQL
6860: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
6870: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a TABLE_WHEN_OPEN.
6880: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 ** flag indicate
6890: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e that a file can
68a0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 not be deleted w
68b0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a hen open. The.*
68c0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 * SQLITE_IOCAP_I
68d0: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e MMUTABLE flag in
68e0: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 dicates that the
68f0: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 file is on.** r
6900: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 ead-only media a
6910: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 nd cannot be cha
6920: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f nged even by pro
6930: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 cesses with.** e
6940: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 levated privileg
6950: 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 es..*/.#define S
6960: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6970: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 IC
6980: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 0x00000001.#d
6990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
69a0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 AP_ATOMIC512
69b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
69c0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
69d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
69e0: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 1K
69f0: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 0x00000004.#def
6a00: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6a10: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 _ATOMIC2K
6a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6a30: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 08.#define SQLIT
6a40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b E_IOCAP_ATOMIC4K
6a50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6a60: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e x00000010.#defin
6a70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6a80: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 TOMIC8K
6a90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
6aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6ab0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 IOCAP_ATOMIC16K
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6ad0: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 0000040.#define
6ae0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6af0: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 MIC32K
6b00: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 0x00000080.#
6b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6b20: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 CAP_ATOMIC64K
6b30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6b40: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00100.#define SQ
6b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
6b60: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 APPEND
6b70: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 0x00000200.#de
6b80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6b90: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 P_SEQUENTIAL
6ba0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6bb0: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 400.#define SQLI
6bc0: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
6bd0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 ABLE_WHEN_OPEN
6be0: 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 0x00000800.#defi
6bf0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6c00: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
6c10: 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 ITE 0x0000100
6c20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6c30: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 _IOCAP_IMMUTABLE
6c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6c50: 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00002000../*.**
6c60: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
6c70: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a ocking Levels.**
6c80: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
6c90: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 one of these int
6ca0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
6cb0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
6cc0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 ument to calls i
6cd0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 t makes to the x
6ce0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
6cf0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 ck() methods.**
6d00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 of an [sqlite3_i
6d10: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
6d20: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t..*/.#define SQ
6d30: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 LITE_LOCK_NONE
6d40: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
6d50: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 e SQLITE_LOCK_SH
6d60: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 ARED 1.#d
6d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6d80: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 K_RESERVED
6d90: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
6da0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 _LOCK_PENDING
6db0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
6dc0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
6dd0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a IVE 4../*.**
6de0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 CAPI3REF: Synch
6df0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 ronization Type
6e00: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e Flags.**.** When
6e10: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
6e20: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
6e30: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
6e40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6e50: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
6e60: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
6e70: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
6e80: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
6e90: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
6ea0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
6eb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
6ec0: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
6ed0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
6ee0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
6ef0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
6f00: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
6f10: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
6f20: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
6f30: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
6f40: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 be flushed. If t
6f50: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
6f60: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a ts of the flag.*
6f70: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 * equal SQLITE_S
6f80: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 YNC_NORMAL, that
6f90: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f means to use no
6fa0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
6fb0: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 antics..** If th
6fc0: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
6fd0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 s equal SQLITE_S
6fe0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d YNC_FULL, that m
6ff0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d eans.** to use M
7000: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
7010: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
7020: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a f fsync()..**.**
7030: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 Do not confuse
7040: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
7050: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
7060: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
7070: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 s.** with the [P
7080: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
7090: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 s]=NORMAL and [P
70a0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
70b0: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 s]=FULL.** setti
70c0: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 ngs. The [synch
70d0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 ronous pragma] d
70e0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 etermines when c
70f0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 alls to the.** x
7100: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 Sync VFS method
7110: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 occur and applie
7120: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f s uniformly acro
7130: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 ss all platforms
7140: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
7150: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
7160: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7170: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 flags determine
7180: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 how.** energeti
7190: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 c or rigorous or
71a0: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 forceful the sy
71b0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 nc operations ar
71c0: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 e and.** only ma
71d0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 ke a difference
71e0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 on Mac OSX for t
71f0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 he default SQLit
7200: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 e code..** (Thir
7210: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c d-party VFS impl
7220: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 ementations migh
7230: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 t also make the
7240: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
7250: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 etween SQLITE_SY
7260: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
7270: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 LITE_SYNC_FULL,
7280: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a but among the.**
7290: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
72a0: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 ms natively supp
72b0: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c orted by SQLite,
72c0: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a only Mac OSX.**
72d0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 cares about the
72e0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f difference.).*/
72f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7300: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 SYNC_NORMAL
7310: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 0x00002.#defi
7320: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 ne SQLITE_SYNC_F
7330: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 ULL 0x0
7340: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 0003.#define SQL
7350: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
7360: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a Y 0x00010..
7370: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
7380: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
7390: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a n File Handle.**
73a0: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
73b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
73c0: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
73d0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
73e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
73f0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
7400: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
7410: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
7420: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
7430: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
7440: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
7450: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
7460: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
7470: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
7480: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
7490: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
74a0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
74b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
74c0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
74d0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
74e0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
74f0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
7500: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
7510: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
7520: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
7530: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
7540: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
7550: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
7560: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
7570: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
7580: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
7590: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
75a0: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
75b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
75c0: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
75d0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
75e0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 ject.**.** Every
75f0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 file opened by
7600: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
7610: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 .xOpen] method p
7620: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b opulates an.** [
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7640: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 ject (or, more c
7650: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c ommonly, a subcl
7660: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ass of the.** [s
7670: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7680: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e ect) with a poin
7690: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
76a0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
76b0: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
76c0: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 t defines the me
76d0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 thods used to pe
76e0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 rform various op
76f0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 erations.** agai
7700: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
7710: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 e represented by
7720: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
7730: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a le] object..**.*
7740: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * If the [sqlite
7750: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7760: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c hod sets the sql
7770: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7780: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 ds element .** t
7790: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 o a non-NULL poi
77a0: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 nter, then the s
77b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
77c0: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a s.xClose method.
77d0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ** may be invoke
77e0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 d even if the [s
77f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7800: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 ] reported that
7810: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a it failed. The.
7820: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 ** only way to p
7830: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f revent a call to
7840: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e xClose followin
7850: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 g a failed [sqli
7860: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a te3_vfs.xOpen].*
7870: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 * is for the [sq
7880: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7890: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
78a0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
78b0: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 s element.** to
78c0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
78d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
78e0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
78f0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
7900: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
7910: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
7920: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
7930: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
7940: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
7950: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
7960: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
7970: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
7980: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
7990: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
79a0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
79b0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
79c0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
79d0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
79e0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
79f0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
7a00: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
7a10: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
7a20: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
7a30: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
7a40: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
7a50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
7a60: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
7a70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
7a80: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
7a90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
7aa0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
7ab0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
7ac0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
7ad0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
7ae0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
7af0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
7b00: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
7b10: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
7b20: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
7b30: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
7b40: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
7b50: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
7b60: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
7b70: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
7b80: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
7b90: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
7ba0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
7bb0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
7bc0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
7bd0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
7be0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
7bf0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
7c00: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
7c10: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
7c20: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
7c30: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
7c40: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
7c50: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
7c60: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
7c70: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
7c80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7c90: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
7ca0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
7cb0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
7cc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
7cd0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
7ce0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
7cf0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
7d00: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
7d10: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
7d20: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
7d30: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
7d40: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
7d50: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
7d60: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
7d70: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
7d80: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
7d90: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
7da0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
7db0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
7dc0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
7dd0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
7de0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
7df0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
7e00: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
7e10: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
7e20: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
7e30: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
7e40: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
7e50: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
7e60: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
7e70: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
7e80: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
7e90: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
7ea0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
7eb0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
7ec0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
7ed0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
7ee0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c A [SQLITE_FCNTL
7ef0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 _LOCKSTATE | lis
7f00: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
7f10: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
7f20: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
7f30: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
7f40: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
7f50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
7f60: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
7f70: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
7f80: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
7f90: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 id conflicts. V
7fa0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
7fb0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ns should.** ret
7fc0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 urn [SQLITE_NOTF
7fd0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 OUND] for file c
7fe0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 ontrol opcodes t
7ff0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
8000: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a ** recognize..**
8010: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
8020: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
8030: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
8040: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
8050: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
8060: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
8070: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
8080: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
8090: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
80a0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
80b0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
80c0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
80d0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
80e0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
80f0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
8100: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
8110: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
8120: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
8130: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
8140: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
8150: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
8160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8170: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
8180: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8190: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
81a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
81b0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
81c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
81d0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
81e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
81f0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
8200: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8210: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
8220: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8230: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <li> [
8240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8250: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <li>
8260: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
8270: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
8280: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
8290: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
82a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
82b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
82c0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
82d0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
82e0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
82f0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
8300: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
8310: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
8320: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
8330: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
8340: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
8350: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
8360: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
8370: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
8380: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
8390: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
83a0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
83b0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
83c0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
83d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
83e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
83f0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
8400: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
8410: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
8420: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
8430: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
8440: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
8450: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
8460: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
8470: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
8480: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
8490: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
84a0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
84b0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
84c0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
84d0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
84e0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
84f0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
8500: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 ()..**.** If xRe
8510: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c ad() returns SQL
8520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
8530: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 READ it must als
8540: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 o fill.** in the
8550: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 unread portions
8560: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 of the buffer w
8570: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 ith zeros. A VF
8580: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 S that.** fails
8590: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
85a0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 rt reads might s
85b0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f eem to work. Ho
85c0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 wever,.** failur
85d0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 e to zero-fill s
85e0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 hort reads will
85f0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 eventually lead
8600: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 to.** database c
8610: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 orruption..*/.ty
8620: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
8630: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
8640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8650: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
8660: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a e3_io_methods {.
8670: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
8680: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
8690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
86a0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 int (*xRead)(s
86b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f qlite3_file*, vo
86c0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
86d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
86e0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 st);. int (*xWr
86f0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ite)(sqlite3_fil
8700: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c e*, const void*,
8710: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
8720: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
8730: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 . int (*xTrunca
8740: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
8750: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8760: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a size);. int (*
8770: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 xSync)(sqlite3_f
8780: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 ile*, int flags)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 ;. int (*xFileS
87a0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
87b0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
87c0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 4 *pSize);. int
87d0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 (*xLock)(sqlite
87e0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
87f0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 int (*xUnlock)(
8800: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8810: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 nt);. int (*xCh
8820: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 eckReservedLock)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8840: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
8850: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 int (*xFileCont
8860: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c rol)(sqlite3_fil
8870: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 e*, int op, void
8880: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *pArg);. int (
8890: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 *xSectorSize)(sq
88a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
88b0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 int (*xDeviceCha
88c0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 racteristics)(sq
88d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
88e0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
88f0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
8900: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e ersion 1 */. in
8910: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c t (*xShmMap)(sql
8920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8930: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 iPg, int pgsz, i
8940: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c nt, void volatil
8950: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 e**);. int (*xS
8960: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f hmLock)(sqlite3_
8970: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 file*, int offse
8980: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c t, int n, int fl
8990: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ags);. void (*x
89a0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 ShmBarrier)(sqli
89b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
89c0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 t (*xShmUnmap)(s
89d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
89e0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 t deleteFlag);.
89f0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
8a00: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
8a10: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 version 2 */. i
8a20: 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c nt (*xFetch)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
8a40: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c te3_int64 iOfst,
8a50: 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 int iAmt, void
8a60: 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 **pp);. int (*x
8a70: 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 Unfetch)(sqlite3
8a80: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
8a90: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 int64 iOfst, voi
8aa0: 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 d *p);. /* Meth
8ab0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
8ac0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
8ad0: 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 3 */. /* Additi
8ae0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 onal methods may
8af0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
8b00: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a ure releases */.
8b10: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
8b20: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c EF: Standard Fil
8b30: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 e Control Opcode
8b40: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e s.**.** These in
8b50: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
8b60: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 are opcodes for
8b70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
8b80: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 method.** of th
8b90: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
8ba0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e thods] object an
8bb0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 d for the [sqlit
8bc0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
8bd0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e )].** interface.
8be0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
8bf0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
8c00: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
8c10: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
8c20: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
8c30: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
8c40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8c50: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
8c60: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
8c70: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
8c80: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
8c90: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
8ca0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
8cb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
8cc0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
8cd0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
8ce0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
8cf0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
8d00: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
8d10: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
8d20: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
8d30: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
8d40: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
8d50: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e g testing and on
8d60: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 ly needs to be s
8d70: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 upported when SQ
8d80: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 LITE_TEST.** is
8d90: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e defined..** <ul>
8da0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
8db0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
8dc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
8dd0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
8de0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 T] opcode is use
8df0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 d by SQLite to g
8e00: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c ive the VFS.** l
8e10: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 ayer a hint of h
8e20: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 ow large the dat
8e30: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
8e40: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e grow to be durin
8e50: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 g the.** current
8e60: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 transaction. T
8e70: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 his hint is not
8e80: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 guaranteed to be
8e90: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 accurate but it
8ea0: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f .** is often clo
8eb0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 se. The underly
8ec0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 ing VFS might ch
8ed0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 oose to prealloc
8ee0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 ate database.**
8ef0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 file space based
8f00: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e on this hint in
8f10: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 order to help w
8f20: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 rites to the dat
8f30: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 abase.** file ru
8f40: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 n faster..**.**
8f50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
8f60: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a TL_CHUNK_SIZE]].
8f70: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
8f80: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d CNTL_CHUNK_SIZE]
8f90: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8fa0: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 to request that
8fb0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e the VFS.** exten
8fc0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 ds and truncates
8fd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
8fe0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 le in chunks of
8ff0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 a size specified
9000: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e .** by the user.
9010: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 The fourth argu
9020: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
9030: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
9040: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e should .** poin
9050: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 t to an integer
9060: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 (type int) conta
9070: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 ining the new ch
9080: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a unk-size to use.
9090: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e ** for the nomin
90a0: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 ated database. A
90b0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 llocating databa
90c0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e se file space in
90d0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 large.** chunks
90e0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 (say 1MB at a t
90f0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 ime), may reduce
9100: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 file-system fra
9110: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a gmentation and.*
9120: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 * improve perfor
9130: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 mance on some sy
9140: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 stems..**.** <li
9150: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9160: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a FILE_POINTER]].*
9170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
9180: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
9190: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
91a0: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 to obtain a poi
91b0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b nter.** to the [
91c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
91d0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 ject associated
91e0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 with a particula
91f0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f r database.** co
9200: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 nnection. See t
9210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
9220: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 _control()] docu
9230: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
9240: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
9250: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c rmation..**.** <
9260: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
9270: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d L_SYNC_OMITTED]]
9280: 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e .** No longer in
9290: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e use..**.** <li>
92a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [[SQLITE_FCNTL_S
92b0: 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 YNC]].** The [SQ
92c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d LITE_FCNTL_SYNC]
92d0: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 opcode is gener
92e0: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 ated internally
92f0: 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a by SQLite and.**
9300: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 sent to the VFS
9310: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 immediately bef
9320: 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 ore the xSync me
9330: 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 thod is invoked
9340: 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 on a.** database
9350: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 file descriptor
9360: 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 . Or, if the xSy
9370: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 nc method is not
9380: 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 invoked .** bec
9390: 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 ause the user ha
93a0: 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c s configured SQL
93b0: 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 ite with .** [PR
93c0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 AGMA synchronous
93d0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 | PRAGMA synchr
93e0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 onous=OFF] it is
93f0: 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 invoked in plac
9400: 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 e .** of the xSy
9410: 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f nc method. In mo
9420: 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f st cases, the po
9430: 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 inter argument p
9440: 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 assed with.** th
9450: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 is file-control
9460: 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 is NULL. However
9470: 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 , if the databas
9480: 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 e file is being
9490: 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 synced.** as par
94a0: 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 t of a multi-dat
94b0: 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 abase commit, th
94c0: 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 e argument point
94d0: 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 s to a nul-termi
94e0: 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 nated.** string
94f0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 containing the t
9500: 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 ransactions mast
9510: 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 er-journal file
9520: 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 name. VFSes that
9530: 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 .** do not need
9540: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f this signal sho
9550: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e uld silently ign
9560: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e ore this opcode.
9570: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a Applications .*
9580: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c * should not cal
9590: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f l [sqlite3_file_
95a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 control()] with
95b0: 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 this opcode as d
95c0: 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 oing so may .**
95d0: 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 disrupt the oper
95e0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 ation of the spe
95f0: 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 cialized VFSes t
9600: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 hat do require i
9610: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b t. .**.** <li>[
9620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f [SQLITE_FCNTL_CO
9630: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a MMIT_PHASETWO]].
9640: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
9650: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 CNTL_COMMIT_PHAS
9660: 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 ETWO] opcode is
9670: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e generated intern
9680: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a ally by SQLite.*
9690: 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 * and sent to th
96a0: 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 e VFS after a tr
96b0: 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 ansaction has be
96c0: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d en committed imm
96d0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 ediately.** but
96e0: 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 before the datab
96f0: 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e ase is unlocked.
9700: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e VFSes that do n
9710: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 ot need this sig
9720: 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 nal.** should si
9730: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 lently ignore th
9740: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 is opcode. Appli
9750: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e cations should n
9760: 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 ot call.** [sqli
9770: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9780: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 ()] with this op
9790: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f code as doing so
97a0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 may disrupt the
97b0: 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f .** operation o
97c0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 f the specialize
97d0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 d VFSes that do
97e0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a require it. .**
97f0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
9800: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
9810: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 RETRY]].** ^The
9820: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 [SQLITE_FCNTL_WI
9830: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 N32_AV_RETRY] op
9840: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
9850: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 configure automa
9860: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 tic.** retry cou
9870: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c nts and interval
9880: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 s for certain di
9890: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e sk I/O operation
98a0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e s for the.** win
98b0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 dows [VFS] in or
98c0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 der to provide r
98d0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 obustness in the
98e0: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 presence of.**
98f0: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 anti-virus progr
9900: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 ams. By default
9910: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 , the windows VF
9920: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c S will retry fil
9930: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 e read,.** file
9940: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 write, and file
9950: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e delete operation
9960: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 s up to 10 times
9970: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a , with a delay.*
9980: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 * of 25 millisec
9990: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 onds before the
99a0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 first retry and
99b0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 with the delay i
99c0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 ncreasing.** by
99d0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 an additional 25
99e0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 milliseconds wi
99f0: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 th each subseque
9a00: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a nt retry. This.
9a10: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 ** opcode allows
9a20: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 these two value
9a30: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e s (10 retries an
9a40: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 d 25 millisecond
9a50: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 s of delay).** t
9a60: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 o be adjusted.
9a70: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 The values are c
9a80: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 hanged for all d
9a90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
9aa0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 ons.** within th
9ab0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 e same process.
9ac0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
9ad0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
9ae0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a array of two.**
9af0: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 integers where
9b00: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 the first intege
9b10: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 r i the new retr
9b20: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 y count and the
9b30: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 second.** intege
9b40: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 r is the delay.
9b50: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 If either integ
9b60: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
9b70: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 then the setting
9b80: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
9b90: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 ed but instead t
9ba0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
9bb0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 f that setting i
9bc0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 s written.** int
9bd0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 o the array entr
9be0: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 y, allowing the
9bf0: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 current retry se
9c00: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 ttings to be.**
9c10: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 interrogated. T
9c20: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d he zDbName param
9c30: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e eter is ignored.
9c40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9c50: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 ITE_FCNTL_PERSIS
9c60: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 T_WAL]].** ^The
9c70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
9c80: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 RSIST_WAL] opcod
9c90: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 e is used to set
9ca0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a or query the.**
9cb0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c persistent [WAL
9cc0: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c | Write Ahead L
9cd0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 og] setting. By
9ce0: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 default, the au
9cf0: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 xiliary.** write
9d00: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 ahead log and s
9d10: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c hared memory fil
9d20: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e es used for tran
9d30: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a saction control.
9d40: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ** are automatic
9d50: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 ally deleted whe
9d60: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e n the latest con
9d70: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 nection to the d
9d80: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 atabase.** close
9d90: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 s. Setting pers
9da0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
9db0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c causes those fil
9dc0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 es to persist af
9dd0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 ter.** close. P
9de0: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 ersisting the fi
9df0: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 les is useful wh
9e00: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 en other process
9e10: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a es that do not.*
9e20: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 * have write per
9e30: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 mission on the d
9e40: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e irectory contain
9e50: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
9e60: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f file want.** to
9e70: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 read the databa
9e80: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 se file, as the
9e90: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d WAL and shared m
9ea0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 emory files must
9eb0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 exist.** in ord
9ec0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 er for the datab
9ed0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 ase to be readab
9ee0: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 le. The fourth
9ef0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
9f00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9f10: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
9f20: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
9f30: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
9f40: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
9f50: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
9f60: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 to disable pers
9f70: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
9f80: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 or 1 to enable p
9f90: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c ersistent.** WAL
9fa0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
9fb0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
9fc0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
9fd0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
9fe0: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 rrent.** WAL per
9ff0: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 sistence setting
a000: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
a010: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
a020: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d SAFE_OVERWRITE]]
a030: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a040: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 _FCNTL_POWERSAFE
a050: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f _OVERWRITE] opco
a060: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 de is used to se
a070: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a t or query the.*
a080: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f * persistent "po
a090: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 wersafe-overwrit
a0a0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 e" or "PSOW" set
a0b0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 ting. The PSOW
a0c0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 setting.** deter
a0d0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 mines the [SQLIT
a0e0: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 E_IOCAP_POWERSAF
a0f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 E_OVERWRITE] bit
a100: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 of the.** xDevi
a110: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
a120: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 s methods. The f
a130: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
a140: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
a150: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 ile_control()] f
a160: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 or this opcode s
a170: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 hould be a point
a180: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
a190: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 ..** That intege
a1a0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c r is 0 to disabl
a1b0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f e zero-damage mo
a1c0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c de or 1 to enabl
a1d0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a e zero-damage.**
a1e0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
a1f0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
a200: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
a210: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
a220: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 rrent.** zero-da
a230: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e mage mode settin
a240: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 g..**.** <li>[[S
a250: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a260: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
a270: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 [SQLITE_FCNTL_OV
a280: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 ERWRITE] opcode
a290: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 is invoked by SQ
a2a0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 Lite after openi
a2b0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 ng.** a write tr
a2c0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 ansaction to ind
a2d0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 icate that, unle
a2e0: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 ss it is rolled
a2f0: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a back for some.**
a300: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 reason, the ent
a310: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ire database fil
a320: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 e will be overwr
a330: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 itten by the cur
a340: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 rent .** transac
a350: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 tion. This is us
a360: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 ed by VACUUM ope
a370: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c rations..**.** <
a380: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
a390: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e L_VFSNAME]].** ^
a3a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
a3b0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 L_VFSNAME] opcod
a3c0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
a3d0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 obtain the name
a3e0: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 s of.** all [VFS
a3f0: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 es] in the VFS s
a400: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 tack. The names
a410: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 are of all VFS
a420: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a shims and the.**
a430: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 final bottom-le
a440: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 vel VFS are writ
a450: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
a460: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a obtained from .*
a470: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
a480: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 c()] and the res
a490: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e ult is stored in
a4a0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 the char* varia
a4b0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ble.** that the
a4c0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
a4d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c of [sqlite3_fil
a4e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 e_control()] poi
a4f0: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 nts to..** The c
a500: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 aller is respons
a510: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 ible for freeing
a520: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e the memory when
a530: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a done. As with.
a540: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 ** all file-cont
a550: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 rol actions, the
a560: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 re is no guarant
a570: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c ee that this wil
a580: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f l actually.** do
a590: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c anything. Call
a5a0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 ers should initi
a5b0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 alize the char*
a5c0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 variable to a NU
a5d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e LL.** pointer in
a5e0: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d case this file-
a5f0: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 control is not i
a600: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 mplemented. Thi
a610: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a s file-control.*
a620: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f * is intended fo
a630: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 r diagnostic use
a640: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 only..**.** <li
a650: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a660: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 PRAGMA]].** ^Whe
a670: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d never a [PRAGMA]
a680: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 statement is pa
a690: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 rsed, an [SQLITE
a6a0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a _FCNTL_PRAGMA] .
a6b0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 ** file control
a6c0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f is sent to the o
a6d0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c pen [sqlite3_fil
a6e0: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 e] object corres
a6f0: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 ponding.** to th
a700: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
a710: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 to which the pra
a720: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 gma statement re
a730: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d fers. ^The argum
a740: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 ent.** to the [S
a750: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a760: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
a770: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a is an array of.
a780: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 ** pointers to s
a790: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 trings (char**)
a7a0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 in which the sec
a7b0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 ond element of t
a7c0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 he array.** is t
a7d0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 he name of the p
a7e0: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 ragma and the th
a7f0: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 ird element is t
a800: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 he argument to t
a810: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 he.** pragma or
a820: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 NULL if the prag
a830: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 ma has no argume
a840: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 nt. ^The handle
a850: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c r for an.** [SQL
a860: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a870: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 ] file control c
a880: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 an optionally ma
a890: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 ke the first ele
a8a0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 ment.** of the c
a8b0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 har** argument p
a8c0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 oint to a string
a8d0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
a8e0: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
a8f0: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 )].** or the equ
a900: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 ivalent and that
a910: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 string will bec
a920: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f ome the result o
a930: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a f the pragma or.
a940: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ** the error mes
a950: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 sage if the prag
a960: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 ma fails. ^If th
a970: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e e.** [SQLITE_FCN
a980: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
a990: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
a9a0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 [SQLITE_NOTFOUND
a9b0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a ], then normal .
a9c0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 ** [PRAGMA] proc
a9d0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 essing continues
a9e0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 . ^If the [SQLI
a9f0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
aa00: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
aa10: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
aa20: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 _OK], then the p
aa30: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 arser assumes th
aa40: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 at the.** VFS ha
aa50: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 s handled the PR
aa60: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 AGMA itself and
aa70: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 the parser gener
aa80: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 ates a no-op.**
aa90: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
aaa0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 nt. ^If the [SQ
aab0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
aac0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
aad0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 returns.** any r
aae0: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 esult code other
aaf0: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
ab00: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 ] or [SQLITE_NOT
ab10: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 FOUND], that mea
ab20: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 ns.** that the V
ab30: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 FS encountered a
ab40: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 n error while ha
ab50: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 ndling the [PRAG
ab60: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 MA] and the.** c
ab70: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 ompilation of th
ab80: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 e PRAGMA fails w
ab90: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e ith an error. ^
aba0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
abb0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
abc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 e control occurs
abd0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e at the beginnin
abe0: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 g of pragma stat
abf0: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 ement analysis a
ac00: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 nd so.** it is a
ac10: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 ble to override
ac20: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 built-in [PRAGMA
ac30: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
ac40: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
ac50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
ac60: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ER]].** ^The [SQ
ac70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
ac80: 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d ANDLER].** file-
ac90: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 control may be i
aca0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 nvoked by SQLite
acb0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
acc0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 file handle.**
acd0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 shortly after it
ace0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 is opened in or
acf0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 der to provide a
ad00: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 custom VFS with
ad10: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 access.** to th
ad20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 e connections bu
ad30: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy-handler callb
ad40: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e ack. The argumen
ad50: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f t is of type (vo
ad60: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 id **).** - an a
ad70: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 rray of two (voi
ad80: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 d *) values. The
ad90: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 first (void *)
ada0: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a actually points.
adb0: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e ** to a function
adc0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a of type (int (*
add0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f )(void *)). In o
ade0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 rder to invoke t
adf0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a he connections.*
ae00: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 * busy-handler,
ae10: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 this function sh
ae20: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 ould be invoked
ae30: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 with the second
ae40: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 (void *) in.** t
ae50: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 he array as the
ae60: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 only argument. I
ae70: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e f it returns non
ae80: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 -zero, then the
ae90: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f operation.** sho
aea0: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 uld be retried.
aeb0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 If it returns ze
aec0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 ro, the custom V
aed0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f FS should abando
aee0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
aef0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a operation..**.*
af00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
af10: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d CNTL_TEMPFILENAM
af20: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 E]].** ^Applicat
af30: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 ion can invoke t
af40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
af50: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 _TEMPFILENAME] f
af60: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 ile-control.** t
af70: 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 o have SQLite ge
af80: 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 nerate a.** temp
af90: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 orary filename u
afa0: 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c sing the same al
afb0: 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 gorithm that is
afc0: 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 followed to gene
afd0: 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 rate.** temporar
afe0: 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 y filenames for
aff0: 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 TEMP tables and
b000: 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 other internal u
b010: 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 ses. The.** arg
b020: 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
b030: 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 a char** which w
b040: 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 ill be filled wi
b050: 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a th the filename.
b060: 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ** written into
b070: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
b080: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
b090: 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 lloc()]. The ca
b0a0: 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 ller should.** i
b0b0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 nvoke [sqlite3_f
b0c0: 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 ree()] on the re
b0d0: 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 sult to avoid a
b0e0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a memory leak..**.
b0f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b100: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d FCNTL_MMAP_SIZE]
b110: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b120: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
b130: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
b140: 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 s used to query
b150: 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 or set the.** ma
b160: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
b170: 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 bytes that will
b180: 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f be used for memo
b190: 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a ry-mapped I/O..*
b1a0: 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 * The argument i
b1b0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
b1c0: 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 value of type s
b1d0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 qlite3_int64 tha
b1e0: 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 t.** is an advis
b1f0: 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 ory maximum numb
b200: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
b210: 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 he file to memor
b220: 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 y map. The.** p
b230: 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 ointer is overwr
b240: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f itten with the o
b250: 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c ld value. The l
b260: 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e imit is not chan
b270: 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 ged if.** the va
b280: 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 lue originally p
b290: 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 ointed to is neg
b2a0: 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 ative, and so th
b2b0: 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 e current limit
b2c0: 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 .** can be queri
b2d0: 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e ed by passing in
b2e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
b2f0: 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e negative number.
b300: 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 This.** file-c
b310: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 ontrol is used i
b320: 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 nternally to imp
b330: 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d lement [PRAGMA m
b340: 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a map_size]..**.**
b350: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b360: 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 NTL_TRACE]].** T
b370: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b380: 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e _TRACE] file con
b390: 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 trol provides ad
b3a0: 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 visory informati
b3b0: 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 on.** to the VFS
b3c0: 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 about what the
b3d0: 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 higher layers of
b3e0: 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 the SQLite stac
b3f0: 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 k are doing..**
b400: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f This file contro
b410: 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d l is used by som
b420: 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 e VFS activity t
b430: 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a racing [shims]..
b440: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
b450: 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e is a zero-termin
b460: 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 ated string. Hi
b470: 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 gher layers in t
b480: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 he.** SQLite sta
b490: 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 ck may generate
b4a0: 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 instances of thi
b4b0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 s file control i
b4c0: 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 f.** the [SQLITE
b4d0: 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 _USE_FCNTL_TRACE
b4e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
b4f0: 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
b500: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
b510: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d LITE_FCNTL_HAS_M
b520: 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 OVED]].** The [S
b530: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
b540: 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 MOVED] file cont
b550: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 rol interprets i
b560: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 ts argument as a
b570: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
b580: 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 n integer and it
b590: 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 writes a boolea
b5a0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 n into that inte
b5b0: 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a ger depending.**
b5c0: 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e on whether or n
b5d0: 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 ot the file has
b5e0: 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f been renamed, mo
b5f0: 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 ved, or deleted
b600: 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 since it.** was
b610: 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a first opened..**
b620: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
b630: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 _FCNTL_WIN32_SET
b640: 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 _HANDLE]].** The
b650: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
b660: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d IN32_SET_HANDLE]
b670: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
b680: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 for debugging.
b690: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 This.** opcode c
b6a0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 auses the xFileC
b6b0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f ontrol method to
b6c0: 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 swap the file h
b6d0: 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f andle with the o
b6e0: 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ne.** pointed to
b6f0: 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 by the pArg arg
b700: 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 ument. This cap
b710: 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 ability is used
b720: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a during testing.*
b730: 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 * and only needs
b740: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
b750: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
b760: 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a T is defined..**
b770: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 .** </ul>.*/.#de
b780: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
b790: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 L_LOCKSTATE
b7a0: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
b7b0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c ine SQLITE_GET_L
b7c0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
b7d0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
b7e0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f ne SQLITE_SET_LO
b7f0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
b800: 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
b810: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 e SQLITE_LAST_ER
b820: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
b830: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
b840: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 SQLITE_FCNTL_SI
b850: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 ZE_HINT
b860: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 5.#define
b870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
b880: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 NK_SIZE
b890: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
b8b0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 _POINTER
b8c0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
b8d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f LITE_FCNTL_SYNC_
b8e0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 OMITTED
b8f0: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
b900: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
b910: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 AV_RETRY
b920: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
b930: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 TE_FCNTL_PERSIST
b940: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 _WAL
b950: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 10.#define SQLIT
b960: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
b970: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 E 1
b980: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
b990: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 _FCNTL_VFSNAME
b9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 12
b9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b9c0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f FCNTL_POWERSAFE_
b9d0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a OVERWRITE 13.
b9e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
b9f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 CNTL_PRAGMA
ba00: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 14.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
ba20: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 NTL_BUSYHANDLER
ba30: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 15.#d
ba40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
ba50: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 TL_TEMPFILENAME
ba60: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 16.#de
ba70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ba80: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 L_MMAP_SIZE
ba90: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 18.#def
baa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bab0: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 _TRACE
bac0: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 19.#defi
bad0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bae0: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 HAS_MOVED
baf0: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 20.#defin
bb00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
bb10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 YNC
bb20: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 21.#define
bb30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f SQLITE_FCNTL_CO
bb40: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 MMIT_PHASETWO
bb50: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 22.#define
bb60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
bb70: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 32_SET_HANDLE
bb80: 20 20 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 23../*.** CA
bb90: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
bba0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d ndle.**.** The m
bbb0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 utex module with
bbc0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 in SQLite define
bbd0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s [sqlite3_mutex
bbe0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 ] to be an.** ab
bbf0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 stract type for
bc00: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 a mutex object.
bc10: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
bc20: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 never looks.**
bc30: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 at the internal
bc40: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f representation o
bc50: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 f an [sqlite3_mu
bc60: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a tex]. It only.*
bc70: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 * deals with poi
bc80: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 nters to the [sq
bc90: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a lite3_mutex] obj
bca0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 ect..**.** Mutex
bcb0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 es are created u
bcc0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 sing [sqlite3_mu
bcd0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f tex_alloc()]..*/
bce0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
bcf0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 sqlite3_mutex sq
bd00: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a lite3_mutex;../*
bd10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
bd20: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 Interface Objec
bd30: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 t.**.** An insta
bd40: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 nce of the sqlit
bd50: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 e3_vfs object de
bd60: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
bd70: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 ace between.** t
bd80: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 he SQLite core a
bd90: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
bda0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
bdb0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a em. The "vfs".*
bdc0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 * in the name of
bdd0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e the object stan
bde0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 ds for "virtual
bdf0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 file system". S
be00: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c ee.** the [VFS |
be10: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 VFS documentati
be20: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 on] for further
be30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
be40: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 ** The value of
be50: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
be60: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 ld is initially
be70: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 1 but may be lar
be80: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 ger in.** future
be90: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
bea0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ite. Additional
beb0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
bec0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a ppended to this.
bed0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 ** object when t
bee0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 he iVersion valu
bef0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 e is increased.
bf00: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 Note that the s
bf10: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 tructure.** of t
bf20: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
bf30: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e bject changes in
bf40: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
bf50: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 between.** SQLi
bf60: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 te version 3.5.9
bf70: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 and 3.6.0 and y
bf80: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 et the iVersion
bf90: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a field was not.**
bfa0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a modified..**.**
bfb0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 The szOsFile fi
bfc0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 eld is the size
bfd0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 of the subclasse
bfe0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d d [sqlite3_file]
bff0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 .** structure us
c000: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 ed by this VFS.
c010: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 mxPathname is t
c020: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
c030: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 h of.** a pathna
c040: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a me in this VFS..
c050: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 **.** Registered
c060: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
c070: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e ects are kept on
c080: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 a linked list f
c090: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ormed by.** the
c0a0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 pNext pointer.
c0b0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
c0c0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 _register()].**
c0d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 and [sqlite3_vfs
c0e0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 _unregister()] i
c0f0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 nterfaces manage
c100: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e this list.** in
c110: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 a thread-safe w
c120: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ay. The [sqlite
c130: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 3_vfs_find()] in
c140: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 terface.** searc
c150: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e hes the list. N
c160: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 either the appli
c170: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 cation code nor
c180: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 the VFS.** imple
c190: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
c1a0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 use the pNext p
c1b0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
c1c0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 e pNext field is
c1d0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 the only field
c1e0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
c1f0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 fs.** structure
c200: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
c210: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 ever modify. S
c220: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 QLite will only
c230: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 access.** or mod
c240: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 ify this field w
c250: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 hile holding a p
c260: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 articular static
c270: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 mutex..** The a
c280: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
c290: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 d never modify a
c2a0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 nything within t
c2b0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
c2c0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 * object once th
c2d0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 e object has bee
c2e0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a n registered..**
c2f0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 .** The zName fi
c300: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 eld holds the na
c310: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f me of the VFS mo
c320: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 dule. The name
c330: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 must.** be uniqu
c340: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 e across all VFS
c350: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 modules..**.**
c360: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [[sqlite3_vfs.xO
c370: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 pen]].** ^SQLite
c380: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
c390: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
c3a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
c3b0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 n.** is either a
c3c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 NULL pointer or
c3d0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
c3e0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 .** from xFullPa
c3f0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e thname() with an
c400: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 optional suffix
c410: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 added..** ^If a
c420: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 suffix is added
c430: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d to the zFilenam
c440: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 e parameter, it
c450: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 will.** consist
c460: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 of a single "-"
c470: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 character follow
c480: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 ed by no more th
c490: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 an.** 11 alphanu
c4a0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 meric and/or "-"
c4b0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 characters..**
c4c0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 ^SQLite further
c4d0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
c4e0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
c4f0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
c500: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
c510: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
c520: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f alled. Because o
c530: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 f the previous s
c540: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 entence,.** the
c550: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 [sqlite3_file] c
c560: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 an safely store
c570: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
c580: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 .** filename if
c590: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 it needs to reme
c5a0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d mber the filenam
c5b0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f e for some reaso
c5c0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 n..** If the zFi
c5d0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
c5e0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e to xOpen is a N
c5f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
c600: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 xOpen.** must i
c610: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 nvent its own te
c620: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 mporary name for
c630: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 the file. ^Whe
c640: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 never the .** xF
c650: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
c660: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c r is NULL it wil
c670: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 l also be the ca
c680: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 se that the.** f
c690: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 lags parameter w
c6a0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c ill include [SQL
c6b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
c6c0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 NCLOSE]..**.** T
c6d0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
c6e0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 t to xOpen() inc
c6f0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 ludes all bits s
c700: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 et in.** the fla
c710: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b gs argument to [
c720: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
c730: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 )]. Or if [sqli
c740: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f te3_open()].** o
c750: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
c760: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 6()] is used, th
c770: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 en flags include
c780: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 s at least.** [S
c790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
c7a0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
c7b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a OPEN_CREATE]. .*
c7c0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 * If xOpen() ope
c7d0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f ns a file read-o
c7e0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 nly then it sets
c7f0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a *pOutFlags to.*
c800: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 * include [SQLIT
c810: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
c820: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e . Other bits in
c830: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 *pOutFlags may
c840: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 be set..**.** ^(
c850: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f SQLite will also
c860: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
c870: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
c880: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a to the xOpen().*
c890: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e * call, dependin
c8a0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 g on the object
c8b0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a being opened:.**
c8c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
c8d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
c8e0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 AIN_DB].** <li>
c8f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
c900: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c IN_JOURNAL].** <
c910: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
c920: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c N_TEMP_DB].** <l
c930: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
c940: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _TEMP_JOURNAL].*
c950: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
c960: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
c970: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
c980: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
c990: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
c9a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
c9b0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c R_JOURNAL].** <l
c9c0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
c9d0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e _WAL].** </ul>)^
c9e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 .**.** The file
c9f0: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 I/O implementati
ca00: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f on can use the o
ca10: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 bject type flags
ca20: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 to.** change th
ca30: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 e way it deals w
ca40: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 ith files. For
ca50: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
ca60: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 ication.** that
ca70: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 does not care ab
ca80: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 out crash recove
ca90: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d ry or rollback m
caa0: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 ight make.** the
cab0: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e open of a journ
cac0: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e al file a no-op.
cad0: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 Writes to this
cae0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a journal would.*
caf0: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 * also be no-ops
cb00: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 , and any attemp
cb10: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f t to read the jo
cb20: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 urnal would retu
cb30: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 rn.** SQLITE_IOE
cb40: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c RR. Or the impl
cb50: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 ementation might
cb60: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 recognize that
cb70: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 a database.** fi
cb80: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 le will be doing
cb90: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 page-aligned se
cba0: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 ctor reads and w
cbb0: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f rites in a rando
cbc0: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 m.** order and s
cbd0: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 et up its I/O su
cbe0: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e bsystem accordin
cbf0: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 gly..**.** SQLit
cc00: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 e might also add
cc10: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
cc20: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
cc30: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a he xOpen method:
cc40: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
cc50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
cc60: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
cc70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
cc80: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a OPEN_EXCLUSIVE].
cc90: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
cca0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
ccb0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 DELETEONCLOSE] f
ccc0: 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
ccd0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 le should be.**
cce0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 deleted when it
ccf0: 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 is closed. ^The
cd00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
cd10: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
cd20: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 will be set for
cd30: 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 TEMP databases a
cd40: 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c nd their journal
cd50: 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 s, transient.**
cd60: 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 databases, and s
cd70: 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a ubjournals..**.*
cd80: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f * ^The [SQLITE_O
cd90: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 PEN_EXCLUSIVE] f
cda0: 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 lag is always us
cdb0: 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f ed in conjunctio
cdc0: 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 n.** with the [S
cdd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
cde0: 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 E] flag, which a
cdf0: 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 re both directly
ce00: 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f .** analogous to
ce10: 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 the O_EXCL and
ce20: 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 O_CREAT flags of
ce30: 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 the POSIX open(
ce40: 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 ).** API. The S
ce50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
ce60: 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 SIVE flag, when
ce70: 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 paired with the
ce80: 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f .** SQLITE_OPEN_
ce90: 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 CREATE, is used
cea0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
ceb0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 file should alw
cec0: 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 ays.** be create
ced0: 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 d, and that it i
cee0: 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 s an error if it
cef0: 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e already exists.
cf00: 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 .** It is <i>not
cf10: 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 </i> used to ind
cf20: 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 icate the file s
cf30: 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 hould be opened
cf40: 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 .** for exclusiv
cf50: 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 e access..**.**
cf60: 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 ^At least szOsFi
cf70: 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f le bytes of memo
cf80: 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 ry are allocated
cf90: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f by SQLite.** to
cfa0: 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 hold the [sqli
cfb0: 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 te3_file] struct
cfc0: 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 ure passed as th
cfd0: 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d e third.** argum
cfe0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 ent to xOpen. T
cff0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
d000: 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
d010: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 .** allocate the
d020: 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 structure; it s
d030: 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 hould just fill
d040: 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 it in. Note tha
d050: 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d t.** the xOpen m
d060: 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 ethod must set t
d070: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
d080: 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 pMethods to eith
d090: 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 er.** a valid [s
d0a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
d0b0: 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 s] object or to
d0c0: 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 NULL. xOpen mus
d0d0: 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 t do.** this eve
d0e0: 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 n if the open fa
d0f0: 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 ils. SQLite exp
d100: 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 ects that the sq
d110: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
d120: 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 ods.** element w
d130: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 ill be valid aft
d140: 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 er xOpen returns
d150: 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
d160: 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 he success.** or
d170: 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 failure of the
d180: 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a xOpen call..**.*
d190: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
d1a0: 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 xAccess]].** ^Th
d1b0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
d1c0: 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 to xAccess() ma
d1d0: 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 y be [SQLITE_ACC
d1e0: 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 ESS_EXISTS].** t
d1f0: 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 o test for the e
d200: 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 xistence of a fi
d210: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
d220: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d CCESS_READWRITE]
d230: 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 to.** test whet
d240: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 her a file is re
d250: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
d260: 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ble, or [SQLITE_
d270: 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 ACCESS_READ].**
d280: 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 to test whether
d290: 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 a file is at lea
d2a0: 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 st readable. T
d2b0: 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 he file can be a
d2c0: 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a .** directory..*
d2d0: 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c *.** ^SQLite wil
d2e0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 l always allocat
d2f0: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 e at least mxPat
d300: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f hname+1 bytes fo
d310: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 r the.** output
d320: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 buffer xFullPath
d330: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 name. The exact
d340: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 size of the out
d350: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
d360: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 also passed as
d370: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 a parameter to b
d380: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 oth methods. If
d390: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
d3a0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 er.** is not lar
d3b0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 ge enough, [SQLI
d3c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f TE_CANTOPEN] sho
d3d0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
d3e0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a Since this is.*
d3f0: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 * handled as a f
d400: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 atal error by SQ
d410: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d Lite, vfs implem
d420: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
d430: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 endeavor.** to
d440: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 prevent this by
d450: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 setting mxPathna
d460: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 me to a sufficie
d470: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 ntly large value
d480: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e ..**.** The xRan
d490: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 domness(), xSlee
d4a0: 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d p(), xCurrentTim
d4b0: 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e e(), and xCurren
d4c0: 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 tTimeInt64().**
d4d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e interfaces are n
d4e0: 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 ot strictly a pa
d4f0: 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 rt of the filesy
d500: 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 stem, but they a
d510: 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 re.** included i
d520: 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 n the VFS struct
d530: 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 ure for complete
d540: 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 ness..** The xRa
d550: 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 ndomness() funct
d560: 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ion attempts to
d570: 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 return nBytes by
d580: 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 tes.** of good-q
d590: 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 uality randomnes
d5a0: 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 s into zOut. Th
d5b0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 e return value i
d5c0: 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 s.** the actual
d5d0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
d5e0: 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 of randomness ob
d5f0: 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 tained..** The x
d600: 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 Sleep() method c
d610: 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e auses the callin
d620: 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 g thread to slee
d630: 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 p for at.** leas
d640: 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
d650: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 microseconds giv
d660: 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 en. ^The xCurre
d670: 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 ntTime().** meth
d680: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c od returns a Jul
d690: 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 ian Day Number f
d6a0: 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 or the current d
d6b0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a ate and time as.
d6c0: 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f ** a floating po
d6d0: 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 int value..** ^T
d6e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
d6f0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 nt64() method re
d700: 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 turns, as an int
d710: 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e eger, the Julian
d720: 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d .** Day Number m
d730: 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 ultiplied by 864
d740: 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 00000 (the numbe
d750: 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
d760: 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f s in .** a 24-ho
d770: 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 ur day). .** ^S
d780: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
d790: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
d7a0: 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f nt64() method to
d7b0: 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 get the current
d7c0: 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d .** date and tim
d7d0: 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 e if that method
d7e0: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 is available (i
d7f0: 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 f iVersion is 2
d800: 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 or .** greater a
d810: 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 nd the function
d820: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
d830: 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 ULL) and will fa
d840: 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 ll back.** to xC
d850: 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 urrentTime() if
d860: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
d870: 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 4() is unavailab
d880: 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 le..**.** ^The x
d890: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c SetSystemCall(),
d8a0: 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xGetSystemCall(
d8b0: 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 ), and xNestSyst
d8c0: 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 emCall() interfa
d8d0: 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 ces.** are not u
d8e0: 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 sed by the SQLit
d8f0: 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f e core. These o
d900: 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 ptional interfac
d910: 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a es are provided.
d920: 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 ** by some VFSes
d930: 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 to facilitate t
d940: 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 esting of the VF
d950: 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 S code. By overr
d960: 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d iding .** system
d970: 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 calls with func
d980: 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 tions under its
d990: 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 control, a test
d9a0: 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 program can.** s
d9b0: 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 imulate faults a
d9c0: 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 nd error conditi
d9d0: 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f ons that would o
d9e0: 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 therwise be diff
d9f0: 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f icult.** or impo
da00: 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 ssible to induce
da10: 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 . The set of sy
da20: 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 stem calls that
da30: 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
da40: 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d n.** varies from
da50: 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 one VFS to anot
da60: 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e her, and from on
da70: 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 e version of the
da80: 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 same VFS to the
da90: 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 .** next. Appli
daa0: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 cations that use
dab0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
dac0: 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 s must be prepar
dad0: 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 ed for any.** or
dae0: 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e all of these in
daf0: 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e terfaces to be N
db00: 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 ULL or for their
db10: 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 behavior to cha
db20: 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 nge.** from one
db30: 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e release to the n
db40: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
db50: 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 ns must not atte
db60: 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a mpt to access.**
db70: 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 any of these me
db80: 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 thods if the iVe
db90: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 rsion of the VFS
dba0: 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e is less than 3.
dbb0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
dbc0: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
dbd0: 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 qlite3_vfs;.type
dbe0: 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
dbf0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 e3_syscall_ptr)(
dc00: 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 void);.struct sq
dc10: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
dc20: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
dc30: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
dc40: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
dc50: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 er (currently 3)
dc60: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
dc70: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
dc80: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
dc90: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
dca0: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
dcb0: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
dcc0: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
dcd0: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
dce0: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
dcf0: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
dd00: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
dd10: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
dd20: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
dd30: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
dd40: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
dd50: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
dd60: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
dd70: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
dd80: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
dd90: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
dda0: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
ddb0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
ddc0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
ddd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
dde0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
ddf0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
de00: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
de10: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
de20: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
de30: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
de40: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
de50: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
de60: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
de70: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
de80: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
de90: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
dea0: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
deb0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
dec0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
ded0: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
dee0: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
def0: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
df00: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
df10: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
df20: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
df30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
df40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
df50: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
df60: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c (*(*xDlSym)(sql
df70: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c ite3_vfs*,void*,
df80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 const char *zSy
df90: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 mbol))(void);.
dfa0: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
dfb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
dfc0: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
dfd0: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
dfe0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
dff0: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
e000: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
e010: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e020: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
e030: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
e040: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
e050: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
e060: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 . int (*xGetLas
e070: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f tError)(sqlite3_
e080: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 vfs*, int, char
e090: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 *);. /*. ** Th
e0a0: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
e0b0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 are in version 1
e0c0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
e0d0: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 fs object. ** d
e0e0: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 efinition. Thos
e0f0: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 e that follow ar
e100: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 e added in versi
e110: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 on 2 or later.
e120: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 */. int (*xCurr
e130: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 entTimeInt64)(sq
e140: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 lite3_vfs*, sqli
e150: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f te3_int64*);. /
e160: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
e170: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
e180: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 versions 1 and 2
e190: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
e1a0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 fs object.. **
e1b0: 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 Those below are
e1c0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e for version 3 an
e1d0: 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a d greater.. */.
e1e0: 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 int (*xSetSyst
e1f0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
e200: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
e210: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
e220: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 _syscall_ptr);.
e230: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
e240: 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 _ptr (*xGetSyste
e250: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
e260: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
e270: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 *zName);. const
e280: 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 char *(*xNextSy
e290: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
e2a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
e2b0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a ar *zName);. /*
e2c0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
e2d0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
e2e0: 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 ersions 1 throug
e2f0: 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 h 3 of the sqlit
e300: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
e310: 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 ** New fields ma
e320: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
e330: 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 figure versions
e340: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
e350: 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
e360: 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
e370: 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
e380: 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a . */.};../*.**
e390: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
e3a0: 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 for the xAccess
e3b0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
e3c0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
e3d0: 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 constants can be
e3e0: 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 used as the thi
e3f0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a rd parameter to.
e400: 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ** the xAccess m
e410: 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c ethod of an [sql
e420: 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
e430: 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e . They determin
e440: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f e.** what kind o
e450: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 f permissions th
e460: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
e470: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e is looking for.
e480: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
e490: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 ACCESS_EXISTS, t
e4a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
e4b0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 d.** simply chec
e4c0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
e4d0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 ile exists..** W
e4e0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
e4f0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
e500: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
e510: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
e520: 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 r the named dire
e530: 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 ctory is both re
e540: 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
e550: 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 ble.** (in other
e560: 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 words, if files
e570: 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 can be added, r
e580: 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 emoved, and rena
e590: 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 med within.** th
e5a0: 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a e directory)..**
e5b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
e5c0: 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e SS_READWRITE con
e5d0: 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 stant is current
e5e0: 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 ly used only by
e5f0: 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f the.** [temp_sto
e600: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
e610: 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 gma], though thi
e620: 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 s could change i
e630: 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 n a future.** re
e640: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
e650: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
e660: 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
e670: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
e680: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
e690: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
e6a0: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c adable. The SQL
e6b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
e6c0: 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 constant is.** c
e6d0: 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c urrently unused,
e6e0: 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 though it might
e6f0: 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 be used in a fu
e700: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a ture release of.
e710: 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 ** SQLite..*/.#d
e720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
e730: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a ESS_EXISTS 0.
e740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
e750: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
e760: 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 1 /* Used by P
e770: 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 RAGMA temp_store
e780: 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 _directory */.#d
e790: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
e7a0: 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 ESS_READ 2
e7b0: 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a /* Unused */..
e7c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
e7d0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 Flags for the xS
e7e0: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f hmLock VFS metho
e7f0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
e800: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
e810: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f define the vario
e820: 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 us locking opera
e830: 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 tions.** allowed
e840: 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b by the xShmLock
e850: 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 method of [sqli
e860: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e te3_io_methods].
e870: 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 The.** followi
e880: 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 ng are the only
e890: 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f legal combinatio
e8a0: 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 ns of flags to t
e8b0: 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d he.** xShmLock m
e8c0: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
e8d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 >.** <li> SQLIT
e8e0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
e8f0: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
e900: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
e910: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 HM_LOCK | SQLITE
e920: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
e930: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
e940: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
e950: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
e960: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
e970: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
e980: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
e990: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 ** </ul>.**.** W
e9a0: 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 hen unlocking, t
e9b0: 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f he same SHARED o
e9c0: 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 r EXCLUSIVE flag
e9d0: 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 must be supplie
e9e0: 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 d as.** was give
e9f0: 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 n no the corresp
ea00: 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a onding lock. .*
ea10: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
ea20: 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 k method can tra
ea30: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
ea40: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 unlocked and SHA
ea50: 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 RED or.** betwee
ea60: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 n unlocked and E
ea70: 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 XCLUSIVE. It ca
ea80: 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 nnot transition
ea90: 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a between SHARED.*
eaa0: 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e * and EXCLUSIVE.
eab0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
eac0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 TE_SHM_UNLOCK
ead0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
eae0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 LITE_SHM_LOCK
eaf0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
eb00: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
eb10: 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e D 4.#defin
eb20: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 e SQLITE_SHM_EXC
eb30: 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a LUSIVE 8../*.
eb40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 ** CAPI3REF: Max
eb50: 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e imum xShmLock in
eb60: 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 dex.**.** The xS
eb70: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e hmLock method on
eb80: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
eb90: 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 hods] may use va
eba0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
ebb0: 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 0 and this upper
ebc0: 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f bound as its "o
ebd0: 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e ffset" argument.
ebe0: 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
ebf0: 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 ore will never a
ec00: 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 ttempt to acquir
ec10: 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a e or release a.*
ec20: 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f * lock outside o
ec30: 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a f this range.*/.
ec40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
ec50: 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 HM_NLOCK
ec60: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8.../*.** CAPI3R
ec70: 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 EF: Initialize T
ec80: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
ec90: 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c y.**.** ^The sql
eca0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ecb0: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
ecc0: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
ecd0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 ite library. ^T
ece0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
ecf0: 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a own() routine.**
ed00: 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 deallocates any
ed10: 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 resources that
ed20: 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 were allocated b
ed30: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 y sqlite3_initia
ed40: 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 lize()..** These
ed50: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
ed60: 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e signed to aid in
ed70: 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c process initial
ed80: 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 ization and.** s
ed90: 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 hutdown on embed
eda0: 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f ded systems. Wo
edb0: 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 rkstation applic
edc0: 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 ations using.**
edd0: 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 SQLite normally
ede0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 do not need to i
edf0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 nvoke either of
ee00: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
ee10: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
ee20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ee30: 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 ze() is an "effe
ee40: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
ee50: 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 t is.** the firs
ee60: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
ee70: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
ee80: 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 nvoked during th
ee90: 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a e lifetime of.**
eea0: 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 the process, or
eeb0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
eec0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
eed0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
eee0: 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c invoked.** foll
eef0: 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 owing a call to
ef00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ef10: 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 (). ^(Only an e
ef20: 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a ffective call.**
ef30: 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 of sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e ialize() does an
ef50: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
ef60: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c . All other cal
ef70: 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 ls.** are harmle
ef80: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a ss no-ops.)^.**.
ef90: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
efa0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
efb0: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
efc0: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
efd0: 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
efe0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
eff0: 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
f000: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
f010: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 nitialize(). ^(
f020: 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
f030: 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
f040: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
f050: 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
f060: 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
f070: 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 l other valid ca
f080: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 lls to sqlite3_s
f090: 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 hutdown() are ha
f0a0: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
f0c0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
f0d0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 interface is thr
f0e0: 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c eadsafe, but sql
f0f0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
f100: 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 ** is not. The
f110: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
f120: 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 () interface mus
f130: 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 t only be called
f140: 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c from a.** singl
f150: 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f e thread. All o
f160: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
f170: 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 nnections] must
f180: 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c be closed and al
f190: 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 l.** other SQLit
f1a0: 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 e resources must
f1b0: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
f1c0: 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e prior to invokin
f1d0: 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 g.** sqlite3_shu
f1e0: 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 tdown()..**.** A
f1f0: 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
f200: 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 s, ^sqlite3_init
f210: 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e ialize() will in
f220: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
f230: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
f240: 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f larly, ^sqlite3_
f250: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 shutdown().** wi
f260: 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
f270: 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
f280: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f290: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f2a0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
f2b0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
f2c0: 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 ss..** ^If for s
f2d0: 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 ome reason, sqli
f2e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f2f0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e is unable to in
f300: 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 itialize.** the
f310: 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 library (perhaps
f320: 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
f330: 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 allocate a need
f340: 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 ed resource such
f350: 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 .** as a mutex)
f360: 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 it returns an [e
f370: 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 rror code] other
f380: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
f390: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
f3a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f3b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 () routine is ca
f3c0: 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 lled internally
f3d0: 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by many other.**
f3e0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
f3f0: 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 es so that an ap
f400: 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c plication usuall
f410: 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 y does not need
f420: 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c to.** invoke sql
f430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f440: 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 ) directly. For
f450: 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 example, [sqlit
f460: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 e3_open()].** ca
f470: 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 lls sqlite3_init
f480: 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 ialize() so the
f490: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
f4a0: 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
f4b0: 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ally.** initiali
f4c0: 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 zed when [sqlite
f4d0: 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 3_open()] is cal
f4e0: 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f led if it has no
f4f0: 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 t be initialized
f500: 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 .** already. ^H
f510: 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 owever, if SQLit
f520: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
f530: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
f540: 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a MIT_AUTOINIT].**
f550: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
f560: 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 tion, then the a
f570: 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 utomatic calls t
f580: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
f590: 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d lize().** are om
f5a0: 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 itted and the ap
f5b0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 plication must c
f5c0: 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 all sqlite3_init
f5d0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
f5e0: 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 y.** prior to us
f5f0: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
f600: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
f610: 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 For maximum por
f620: 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 tability,.** it
f630: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
f640: 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
f650: 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 always invoke s
f660: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
f670: 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 e().** directly
f680: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
f690: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
f6a0: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 interface. Futu
f6b0: 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f re releases.** o
f6c0: 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 f SQLite may req
f6d0: 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f uire this. In o
f6e0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
f6f0: 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 behavior exhibit
f700: 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 ed.** when SQLit
f710: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
f720: 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f th [SQLITE_OMIT_
f730: 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 AUTOINIT] might
f740: 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 become the.** de
f750: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
f760: 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
f770: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
f780: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
f790: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 e3_os_init() rou
f7a0: 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 tine does operat
f7b0: 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
f7c0: 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a fic.** initializ
f7d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c ation of the SQL
f7e0: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
f7f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
f800: 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e ().** routine un
f810: 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 does the effect
f820: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
f830: 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 it(). Typical t
f840: 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 asks.** performe
f850: 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 d by these routi
f860: 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f nes include allo
f870: 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f cation or deallo
f880: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 cation.** of sta
f890: 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 tic resources, i
f8a0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
f8b0: 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
f8c0: 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 s,.** setting up
f8d0: 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 a default [sqli
f8e0: 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c te3_vfs] module,
f8f0: 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a or setting up.*
f900: 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 * a default conf
f910: 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 iguration using
f920: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
f930: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 )]..**.** The ap
f940: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
f950: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 never invoke ei
f960: 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ther sqlite3_os_
f970: 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c init().** or sql
f980: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 ite3_os_end() di
f990: 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 rectly. The app
f9a0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
f9b0: 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 only invoke.** s
f9c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
f9d0: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 shutdown(). The
f9f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
fa00: 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
fa10: 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 is called automa
fa20: 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
fa30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
fa40: 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f and.** sqlite3_o
fa50: 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 s_end() is calle
fa60: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 d by sqlite3_shu
fa70: 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 tdown(). Approp
fa80: 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 riate.** impleme
fa90: 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c ntations for sql
faa0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
fab0: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
fac0: 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 d().** are built
fad0: 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 into SQLite whe
fae0: 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
faf0: 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f for Unix, Windo
fb00: 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 ws, or OS/2..**
fb10: 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 When [custom bui
fb20: 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 lds | built for
fb30: 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d other platforms]
fb40: 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b .** (using the [
fb50: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d SQLITE_OS_OTHER=
fb60: 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 1] compile-time.
fb70: 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 ** option) the a
fb80: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
fb90: 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c supply a suitabl
fba0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
fbb0: 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
fbc0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
fbd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 lite3_os_end().
fbe0: 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
fbf0: 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c supplied.** impl
fc00: 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
fc10: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
fc20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
fc30: 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 d().** must retu
fc40: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
fc50: 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f n success and so
fc60: 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 me other [error
fc70: 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 code] upon.** fa
fc80: 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ilure..*/.int sq
fc90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
fca0: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
fcb0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 te3_shutdown(voi
fcc0: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f d);.int sqlite3_
fcd0: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 os_init(void);.i
fce0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nt sqlite3_os_en
fcf0: 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d(void);../*.**
fd00: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
fd10: 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 uring The SQLite
fd20: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 Library.**.** T
fd30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 he sqlite3_confi
fd40: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
fd50: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c used to make gl
fd60: 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 obal configurati
fd70: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
fd80: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
fd90: 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 to tune SQLite
fda0: 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 to the specific
fdb0: 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 needs of.** the
fdc0: 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 application. Th
fdd0: 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 e default config
fde0: 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d uration is recom
fdf0: 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a mended for most.
fe00: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
fe10: 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 and so this rout
fe20: 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e ine is usually n
fe30: 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 ot necessary. I
fe40: 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 t is.** provided
fe50: 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 to support rare
fe60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 applications wi
fe70: 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 th unusual needs
fe80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
fe90: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
fea0: 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 erface is not th
feb0: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 readsafe. The a
fec0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 pplication.** mu
fed0: 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e st insure that n
fee0: 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 o other SQLite i
fef0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e nterfaces are in
ff00: 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a voked by other.*
ff10: 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 * threads while
ff20: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
ff30: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 is running. Fu
ff40: 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 rthermore, sqlit
ff50: 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d e3_config().** m
ff60: 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b ay only be invok
ff70: 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 ed prior to libr
ff80: 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ary initializati
ff90: 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c on using.** [sql
ffa0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ffb0: 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 )] or after shut
ffc0: 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 down by [sqlite3
ffd0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a _shutdown()]..**
ffe0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e ^If sqlite3_con
fff0: 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 fig() is called
10000 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 after [sqlite3_i
10010 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 nitialize()] and
10020 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 before.** [sqli
10030 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
10040 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 then it will ret
10050 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 urn SQLITE_MISUS
10060 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 E..** Note, howe
10070 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 ver, that ^sqlit
10080 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 e3_config() can
10090 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 be called as par
100a0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c t of the.** impl
100b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e ementation of an
100c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
100d0 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 ined [sqlite3_os
100e0 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _init()]..**.**
100f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
10100 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f nt to sqlite3_co
10110 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 nfig() is an int
10120 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 eger.** [configu
10130 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 ration option] t
10140 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a hat determines.*
10150 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 * what property
10160 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 of SQLite is to
10170 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 be configured.
10180 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d Subsequent argum
10190 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 ents.** vary dep
101a0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 ending on the [c
101b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
101c0 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
101d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
101e0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e *.** ^When a con
101f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
10200 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 n is set, sqlite
10210 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 3_config() retur
10220 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
10230 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f ** ^If the optio
10240 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 n is unknown or
10250 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 SQLite is unable
10260 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 to set the opti
10270 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 on.** then this
10280 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
10290 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f a non-zero [erro
102a0 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 r code]..*/.int
102b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 sqlite3_config(i
102c0 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a nt, ...);../*.**
102d0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
102e0 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f gure database co
102f0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 nnections.**.**
10300 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 The sqlite3_db_c
10310 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
10320 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
10330 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a e configuration.
10340 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 ** changes to a
10350 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10360 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 tion]. The inte
10370 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 rface is similar
10380 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
10390 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 config()] except
103a0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 that the change
103b0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e s apply to a sin
103c0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 gle.** [database
103d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 connection] (sp
103e0 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 ecified in the f
103f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a irst argument)..
10400 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
10410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
10420 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
10430 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
10440 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e ** [SQLITE_DBCON
10450 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 FIG_LOOKASIDE |
10460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
10470 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 rb] - an integer
10480 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 code .** that i
10490 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 ndicates what as
104a0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
104b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
104c0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
104d0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 gured..** Subseq
104e0 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 uent arguments v
104f0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
10500 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
10510 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e on verb..**.** ^
10520 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
10530 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 _db_config() ret
10540 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
10550 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
10560 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 the call is cons
10570 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 idered successfu
10580 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 l..*/.int sqlite
10590 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 3_db_config(sqli
105a0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e te3*, int op, ..
105b0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
105c0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
105d0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a cation Routines.
105e0 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
105f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
10600 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
10610 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
10620 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
10630 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
10640 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
10650 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
10660 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
10670 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
10680 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
10690 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
106a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
106b0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
106c0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
106d0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
106e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
106f0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
10700 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
10710 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
10720 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 ALLOC] or [SQLIT
10730 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
10740 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 OC]. .** By cre
10750 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
10760 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
10770 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
10780 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
10790 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
107a0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a ONFIG_MALLOC]).*
107b0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 * during configu
107c0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 ration, an appli
107d0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
107e0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
107f0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
10800 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
10810 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
10820 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
10830 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d s.** dynamic mem
10840 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
10850 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
10860 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 e comes with sev
10870 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d eral [built-in m
10880 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
10890 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 ].** that are pe
108a0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
108b0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
108c0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
108d0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
108e0 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
108f0 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
10900 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
10910 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
10920 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
10930 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
10940 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
10950 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
10960 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
10970 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
10980 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
10990 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
109a0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
109b0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
109c0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
109d0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
109e0 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
109f0 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
10a00 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
10a10 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
10a20 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
10a30 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
10a40 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
10a50 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c e xMalloc, xReal
10a60 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d loc, and xFree m
10a70 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b ethods must work
10a80 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c like the.** mal
10a90 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 loc(), realloc()
10aa0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 and free() func
10ab0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 tions from the s
10ac0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
10ad0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 y..** ^SQLite gu
10ae0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
10af0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
10b00 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 t to.** xRealloc
10b10 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c is always a val
10b20 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 ue returned by a
10b30 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 prior call to x
10b40 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 Roundup..**.** x
10b50 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
10b60 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
10b70 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
10b80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
10b90 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
10ba0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
10bb0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
10bc0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
10bd0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
10be0 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
10bf0 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
10c00 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
10c10 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
10c20 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
10c30 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
10c40 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
10c50 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
10c60 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
10c70 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
10c80 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
10c90 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
10ca0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
10cb0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
10cc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
10cd0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
10ce0 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
10cf0 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
10d00 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
10d10 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
10d20 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
10d30 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 er of 2..** Ever
10d40 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
10d50 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 ion request comi
10d60 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 ng in through [s
10d70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
10d80 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
10d90 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 realloc()] first
10da0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e calls xRoundup.
10db0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 If xRoundup re
10dc0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 turns 0, .** tha
10dd0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 t causes the cor
10de0 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 responding memor
10df0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
10e00 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fail..**.** The
10e10 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 xInit method ini
10e20 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d tializes the mem
10e30 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 ory allocator.
10e40 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 For example,.**
10e50 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 it might allocat
10e60 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 e any require mu
10e70 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c texes or initial
10e80 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 ize internal dat
10e90 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e a.** structures.
10ea0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 The xShutdown
10eb0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
10ec0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 d (indirectly) b
10ed0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 y.** [sqlite3_sh
10ee0 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 utdown()] and sh
10ef0 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 ould deallocate
10f00 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 any resources ac
10f10 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e quired.** by xIn
10f20 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 it. The pAppDat
10f30 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 a pointer is use
10f40 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 d as the only pa
10f50 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 rameter to.** xI
10f60 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 nit and xShutdow
10f70 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
10f80 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
10f90 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
10fa0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 ASTER] mutex whe
10fb0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 n it invokes.**
10fc0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 the xInit method
10fd0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d , so the xInit m
10fe0 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 ethod need not b
10ff0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 e threadsafe. T
11000 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 he.** xShutdown
11010 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 method is only c
11020 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 alled from [sqli
11030 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
11040 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f so it does.** no
11050 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 t need to be thr
11060 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 eadsafe either.
11070 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d For all other m
11080 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a ethods, SQLite.*
11090 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c * holds the [SQL
110a0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
110b0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c _MEM] mutex as l
110c0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 ong as the.** [S
110d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
110e0 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 STATUS] configur
110f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
11100 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 turned on (which
11110 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 .** it is by def
11120 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 ault) and so the
11130 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 methods are aut
11140 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 omatically seria
11150 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 lized..** Howeve
11160 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f r, if [SQLITE_CO
11170 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
11180 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 is disabled, the
11190 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d n the other.** m
111a0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 ethods must be t
111b0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 hreadsafe or els
111c0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e e make their own
111d0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f arrangements fo
111e0 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 r.** serializati
111f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
11200 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f will never invo
11210 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 ke xInit() more
11220 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 than once withou
11230 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 t an intervening
11240 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 .** call to xShu
11250 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 tdown()..*/.type
11260 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
11270 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 e3_mem_methods s
11280 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
11290 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
112a0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b e3_mem_methods {
112b0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c . void *(*xMall
112c0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 oc)(int);
112d0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f /* Memory allo
112e0 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 cation function
112f0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 */. void (*xFre
11300 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
11310 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 /* Free a pr
11320 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a ior allocation *
11330 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 /. void *(*xRea
11340 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 lloc)(void*,int)
11350 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 ; /* Resize an
11360 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
11370 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 int (*xSize)(voi
11380 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
11390 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a * Return the siz
113a0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 e of an allocati
113b0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 on */. int (*xR
113c0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 oundup)(int);
113d0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 /* Round
113e0 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 up request size
113f0 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 to allocation si
11400 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 ze */. int (*xI
11410 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 nit)(void*);
11420 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 /* Initia
11430 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
11440 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
11450 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 oid (*xShutdown)
11460 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a (void*); /*
11470 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 Deinitialize th
11480 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
11490 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 or */. void *pA
114a0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
114b0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 /* Argume
114c0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e nt to xInit() an
114d0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f d xShutdown() */
114e0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
114f0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 REF: Configurati
11500 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 on Options.** KE
11510 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 YWORDS: {configu
11520 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a ration option}.*
11530 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
11540 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
11550 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
11560 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11570 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
11580 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
11590 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
115a0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
115b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
115c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
115d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
115e0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
115f0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
11600 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
11610 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
11620 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11630 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
11640 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
11650 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
11660 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
11670 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
11680 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
11690 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
116a0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
116b0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
116c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
116d0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
116e0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
116f0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
11700 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
11710 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
11720 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
11730 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
11740 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
11750 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
11760 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d G_SINGLETHREAD]]
11770 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
11780 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
11790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
117a0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
117b0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
117c0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
117d0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
117e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
117f0 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 Single-thread.
11800 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
11810 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
11820 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
11830 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
11840 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
11850 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
11860 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
11870 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 e thread. ^If
11880 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
11890 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
118a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
118b0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
118c0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
118d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
118e0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
118f0 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 ossible to chang
11900 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
11910 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 mode] from its
11920 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
11930 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 of Single-threa
11940 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 d and so [sqlite
11950 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
11960 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c return .** [SQL
11970 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
11980 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 lled with the SQ
11990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
119a0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 LETHREAD.** conf
119b0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
119c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
119d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
119e0 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 TITHREAD]] <dt>S
119f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
11a00 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a TITHREAD</dt>.**
11a10 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
11a20 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
11a30 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
11a40 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
11a50 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
11a60 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
11a70 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 thread. In othe
11a80 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 r words, it disa
11a90 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
11aa0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
11ab0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
11ac0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11ad0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
11ae0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
11af0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
11b00 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
11b10 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
11b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
11b30 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
11b40 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
11b50 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
11b60 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
11b70 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
11b80 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
11b90 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
11ba0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
11bb0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
11bc0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
11bd0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
11be0 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
11bf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
11c00 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
11c10 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 . ^If SQLite is
11c20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
11c30 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
11c40 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
11c50 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
11c60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
11c70 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
11c80 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
11c90 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d o set the Multi-
11ca0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
11cb0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
11cc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
11cd0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
11ce0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
11cf0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
11d00 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
11d10 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e _MULTITHREAD con
11d20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11d30 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
11d40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
11d50 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 RIALIZED]] <dt>S
11d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
11d70 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 IALIZED</dt>.**
11d80 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
11d90 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
11da0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
11db0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
11dc0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
11dd0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 mode] to Seriali
11de0 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f zed. In other wo
11df0 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e rds, this option
11e00 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
11e10 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
11e20 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
11e30 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
11e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11e50 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
11e60 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
11e70 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
11e80 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
11e90 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
11ea0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
11eb0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
11ec0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
11ed0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
11ee0 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
11ef0 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
11f00 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
11f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
11f20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
11f30 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
11f40 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
11f50 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
11f60 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
11f70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11f80 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
11f90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
11fa0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
11fb0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
11fc0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
11fd0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
11fe0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
11ff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
12000 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
12010 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
12020 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
12030 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
12040 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
12050 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a set the Serializ
12060 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
12070 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
12080 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
12090 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
120a0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
120b0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
120c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
120d0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 IALIZED configur
120e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
120f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12100 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
12110 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12120 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a FIG_MALLOC</dt>.
12130 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f ** <dd> ^(This o
12140 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
12150 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
12160 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ich is a pointer
12170 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e to an.** instan
12180 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
12190 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
121a0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 structure. The
121b0 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
121c0 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
121d0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
121e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
121f0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
12200 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
12210 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
12220 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
12230 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
12240 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b e.)^ ^SQLite mak
12250 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 es.** its own pr
12260 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
12270 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
12280 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
12290 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
122a0 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
122b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
122c0 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c ] call returns.<
122d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
122e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
122f0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
12300 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
12310 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
12320 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
12330 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
12340 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
12350 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
12360 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 * instance of th
12370 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
12380 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
12390 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 e. The [sqlite3
123a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
123b0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
123c0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
123d0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
123e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
123f0 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a n routines.)^.**
12400 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
12410 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
12420 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
12430 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12440 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
12450 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
12460 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
12470 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12480 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
12490 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
124a0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
124b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
124c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
124d0 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c STATUS]] <dt>SQL
124e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
124f0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATUS</dt>.** <dd
12500 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 > ^This option t
12510 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 akes single argu
12520 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
12530 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 , interpreted as
12540 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 a .** boolean,
12550 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 which enables or
12560 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f disables the co
12570 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f llection of memo
12580 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a ry allocation .*
12590 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 * statistics. ^(
125a0 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f When memory allo
125b0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
125c0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 s are disabled,
125d0 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e the .** followin
125e0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 g SQLite interfa
125f0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f ces become non-o
12600 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 perational:.**
12610 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 <ul>.** <li>
12620 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
12630 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 used()].** <li
12640 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 > [sqlite3_memor
12650 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a y_highwater()].*
12660 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
12670 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 3_soft_heap_limi
12680 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e t64()].** <li>
12690 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 [sqlite3_status
126a0 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e ()].** </ul>)^
126b0 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f .** ^Memory allo
126c0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
126d0 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 s are enabled by
126e0 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 default unless
126f0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d SQLite is.** com
12700 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 piled with [SQLI
12710 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 TE_DEFAULT_MEMST
12720 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 ATUS]=0 in which
12730 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 case memory.**
12740 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
12750 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c stics are disabl
12760 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
12770 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
12780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
12790 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 RATCH]] <dt>SQLI
127a0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
127b0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e H</dt>.** <dd> ^
127c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 This option spec
127d0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
127e0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 emory buffer tha
127f0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
12800 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 for.** scratch
12810 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 memory. There a
12820 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
12830 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 ts: A pointer a
12840 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 n 8-byte.** alig
12850 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 ned memory buffe
12860 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 r from which the
12870 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
12880 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 ions will be.**
12890 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 drawn, the size
128a0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 of each scratch
128b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c allocation (sz),
128c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 .** and the maxi
128d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 mum number of sc
128e0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
128f0 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a s (N). The sz.*
12900 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 * argument must
12910 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 be a multiple of
12920 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 16..** The firs
12930 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
12940 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
12950 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 an 8-byte aligne
12960 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 d buffer.** of a
12970 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
12980 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
12990 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
129a0 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 e no more than t
129b0 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 wo scratch buffe
129c0 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 rs per thread.
129d0 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 So.** N should b
129e0 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 e set to twice t
129f0 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 he expected maxi
12a00 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 mum number of th
12a10 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 reads..** ^SQLit
12a20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 e will never req
12a30 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 uire a scratch b
12a40 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f uffer that is mo
12a50 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d re than 6.** tim
12a60 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
12a70 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 page size. ^If S
12a80 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 QLite needs need
12a90 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 s additional.**
12aa0 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 scratch memory b
12ab0 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
12ac0 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 ovided by this c
12ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12ae0 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 ion, then .** [s
12af0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
12b00 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f will be used to
12b10 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f obtain the memo
12b20 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a ry needed.</dd>.
12b30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
12b40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
12b50 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12b60 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 FIG_PAGECACHE</d
12b70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
12b80 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
12b90 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
12ba0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
12bb0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
12bc0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
12bd0 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 page cache with
12be0 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 the default pag
12bf0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
12c00 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 tation. .** Thi
12c10 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
12c20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 should not be us
12c30 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 ed if an applica
12c40 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 tion-define page
12c50 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d .** cache implem
12c60 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 entation is load
12c70 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c ed using the SQL
12c80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
12c90 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 E2 option..** Th
12ca0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
12cb0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
12cc0 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 option: A pointe
12cd0 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 r to 8-byte alig
12ce0 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 ned.** memory, t
12cf0 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 he size of each
12d00 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 page buffer (sz)
12d10 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 , and the number
12d20 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a of pages (N)..*
12d30 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e * The sz argumen
12d40 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 t should be the
12d50 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 size of the larg
12d60 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 est database pag
12d70 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 e.** (a power of
12d80 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 two between 512
12d90 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 and 32768) plus
12da0 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 a little extra
12db0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 for each.** page
12dc0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 header. ^The p
12dd0 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 age header size
12de0 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 is 20 to 40 byte
12df0 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a s depending on.*
12e00 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 * the host archi
12e10 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 tecture. ^It is
12e20 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 harmless, apart
12e30 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 from the wasted
12e40 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d memory,.** to m
12e50 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 ake sz a little
12e60 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 too large. The
12e70 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e first.** argumen
12e80 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 t should point t
12e90 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 o an allocation
12ea0 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
12eb0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
12ec0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c ..** ^SQLite wil
12ed0 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 l use the memory
12ee0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 provided by the
12ef0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
12f00 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a to satisfy its.*
12f10 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 * memory needs f
12f20 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 or the first N p
12f30 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 ages that it add
12f40 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 s to cache. ^If
12f50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 additional.** p
12f60 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 age cache memory
12f70 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e is needed beyon
12f80 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
12f90 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f ed by this optio
12fa0 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 n, then.** SQLit
12fb0 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 e goes to [sqlit
12fc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 e3_malloc()] for
12fd0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 the additional
12fe0 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a storage space..*
12ff0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e * The pointer in
13000 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
13010 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 ent must.** be a
13020 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 ligned to an 8-b
13030 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 yte boundary or
13040 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 subsequent behav
13050 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a ior of SQLite.**
13060 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e will be undefin
13070 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ed.</dd>.**.** [
13080 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 [SQLITE_CONFIG_H
13090 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAP]] <dt>SQLITE
130a0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 _CONFIG_HEAP</dt
130b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
130c0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
130d0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
130e0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c buffer that SQL
130f0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
13100 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 for all of its d
13110 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c ynamic memory al
13120 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 location needs b
13130 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 eyond those prov
13140 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b ided.** for by [
13150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
13160 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 RATCH] and [SQLI
13170 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
13180 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 CHE]..** There a
13190 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
131a0 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c ts: An 8-byte al
131b0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f igned pointer to
131c0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 the memory,.**
131d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
131e0 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 tes in the memor
131f0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 y buffer, and th
13200 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
13210 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 tion size..** ^I
13220 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e f the first poin
13230 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
13240 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c pointer) is NULL
13250 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 , then SQLite re
13260 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e verts.** to usin
13270 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 g its default me
13280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 mory allocator (
13290 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
132a0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 c() implementati
132b0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 on),.** undoing
132c0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 any prior invoca
132d0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f tion of [SQLITE_
132e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 CONFIG_MALLOC].
132f0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f ^If the.** memo
13300 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f ry pointer is no
13310 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 t NULL and eithe
13320 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
13330 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 _MEMSYS3] or.**
13340 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d [SQLITE_ENABLE_M
13350 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 EMSYS5] are defi
13360 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c ned, then the al
13370 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 ternative memory
13380 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 .** allocator is
13390 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 engaged to hand
133a0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 le all of SQLite
133b0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
133c0 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 ion needs..** Th
133d0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
133e0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
133f0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 ter) must be ali
13400 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
13410 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 e.** boundary or
13420 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
13430 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 vior of SQLite w
13440 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 ill be undefined
13450 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d ..** The minimum
13460 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
13470 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a is capped at 2*
13480 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 *12. Reasonable
13490 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 values.** for th
134a0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
134b0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a tion size are 2*
134c0 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e *5 through 2**8.
134d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
134e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
134f0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 X]] <dt>SQLITE_C
13500 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
13520 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
13530 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
13540 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
13550 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
13560 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
13570 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
13580 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
13590 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 he argument spec
135a0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 ifies.** alterna
135b0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
135c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f utex routines to
135d0 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
135e0 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 e.** the mutex r
135f0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
13600 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 to SQLite.)^ ^S
13610 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
13620 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e py of the.** con
13630 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
13640 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13650 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 ds] structure be
13660 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f fore the call to
13670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
13680 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 fig()] returns.
13690 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
136a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
136b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
136c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
136d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
136e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
136f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
13700 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
13710 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
13720 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
13730 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
13740 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
13750 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
13760 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13770 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 _MUTEX configura
13780 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
13790 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
137a0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
137b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
137c0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d ONFIG_GETMUTEX]]
137d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
137e0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e IG_GETMUTEX</dt>
137f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
13800 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
13810 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
13820 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
13830 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
13840 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
13850 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
13860 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
13870 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
13880 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a utex_methods].**
13890 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
138a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
138b0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
138c0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 mutex routines.)
138d0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
138e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
138f0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
13900 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 ault mutex alloc
13910 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
13920 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
13930 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d used to track m
13940 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 utex usage for p
13950 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 erformance.** pr
13960 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 ofiling or testi
13970 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ng, for example.
13980 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
13990 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
139a0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
139b0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
139c0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
139d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
139e0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
139f0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
13a00 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
13a10 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
13a20 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
13a30 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
13a40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
13a50 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
13a60 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e FIG_GETMUTEX con
13a70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
13a80 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
13a90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
13aa0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
13ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
13ac0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 ASIDE]] <dt>SQLI
13ad0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
13ae0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
13af0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
13b00 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e akes two argumen
13b10 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e ts that determin
13b20 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a e the default.**
13b30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13b40 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 on for the looka
13b50 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f side memory allo
13b60 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a cator on each.**
13b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
13b80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 ction]. The fir
13b90 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 st argument is t
13ba0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
13bb0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
13bc0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 fer slot and the
13bd0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e second is the n
13be0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
13bf0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 s allocated to e
13c00 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
13c10 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 nection.)^ ^(Th
13c20 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
13c30 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 he.** <i>default
13c40 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 </i> lookaside s
13c50 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 ize. The [SQLITE
13c60 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
13c70 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 IDE].** verb to
13c80 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
13c90 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 ig()] can be use
13ca0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
13cb0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e lookaside.** con
13cc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e figuration on in
13cd0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 dividual connect
13ce0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ions.)^ </dd>.**
13cf0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
13d00 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 FIG_PCACHE2]] <d
13d10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13d20 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
13d30 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
13d40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
13d50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
13d60 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
13d70 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f .** an [sqlite3_
13d80 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
13d90 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f object. This o
13da0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 bject specifies
13db0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
13dc0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 to a custom pag
13dd0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
13de0 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 tation.)^ ^SQLi
13df0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
13e00 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 of the.** object
13e10 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 and uses it for
13e20 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
13e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c ry allocations.<
13e40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
13e50 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
13e60 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
13e70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
13e80 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 CHE2</dt>.** <dd
13e90 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
13ea0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
13eb0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
13ec0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
13ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 .** [sqlite3_pca
13ee0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
13ef0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
13f00 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 pies of the curr
13f10 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 ent.** page cach
13f20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
13f30 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
13f40 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a t.)^ </dd>.**.**
13f50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13f60 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _LOG]] <dt>SQLIT
13f70 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 E_CONFIG_LOG</dt
13f80 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 >.** <dd> The SQ
13f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
13fa0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
13fb0 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 o configure the
13fc0 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c SQLite.** global
13fd0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a [error log]..**
13fe0 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f (^The SQLITE_CO
13ff0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 NFIG_LOG option
14000 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
14010 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 nts: a pointer t
14020 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 o a.** function
14030 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e with a call sign
14040 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 ature of void(*)
14050 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
14060 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 char*), .** and
14070 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f a pointer to vo
14080 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 id. ^If the func
14090 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
140a0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a not NULL, it is.
140b0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 ** invoked by [s
140c0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f qlite3_log()] to
140d0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f process each lo
140e0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 gging event. ^I
140f0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
14100 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c n pointer is NUL
14110 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f L, the [sqlite3_
14120 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 log()] interface
14130 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 becomes a no-op
14140 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 ..** ^The void p
14150 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 ointer that is t
14160 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
14170 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e nt to SQLITE_CON
14180 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 FIG_LOG is.** pa
14190 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
141a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
141b0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 ter to the appli
141c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c cation-defined l
141d0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f ogger.** functio
141e0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 n whenever that
141f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f function is invo
14200 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e ked. ^The secon
14210 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
14220 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e * the logger fun
14230 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 ction is a copy
14240 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 of the first par
14250 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f ameter to the co
14260 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b rresponding.** [
14270 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 sqlite3_log()] c
14280 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e all and is inten
14290 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 ded to be a [res
142a0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a ult code] or an.
142b0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
142c0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 ult code]. ^The
142d0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
142e0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c passed to the l
142f0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 ogger is.** log
14300 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f message after fo
14310 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 rmatting via [sq
14320 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
14330 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 ]..** The SQLite
14340 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 logging interfa
14350 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 ce is not reentr
14360 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 ant; the logger
14370 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 function.** supp
14380 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c lied by the appl
14390 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
143a0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 invoke any SQLi
143b0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a te interface..**
143c0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 In a multi-thre
143d0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
143e0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
143f0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
14400 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
14410 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
14420 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
14430 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
14440 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
14450 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e NFIG_URI.** <dd>
14460 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^(This option ta
14470 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
14480 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
14490 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 t. If non-zero,
144a0 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 then.** URI hand
144b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 ling is globally
144c0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 enabled. If the
144d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 parameter is ze
144e0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e ro, then URI han
144f0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 dling.** is glob
14500 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e ally disabled.)^
14510 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e ^If URI handlin
14520 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
14530 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
14540 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 ames.** passed t
14550 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
14560 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
14570 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 n_v2()], [sqlite
14580 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
14590 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
145a0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
145b0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
145c0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
145d0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
145e0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
145f0 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
14600 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
14610 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
14620 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
14630 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e ion is opened. ^
14640 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c If it is globall
14650 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 y disabled, file
14660 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c names are.** onl
14670 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 y interpreted as
14680 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c URIs if the SQL
14690 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 ITE_OPEN_URI fla
146a0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
146b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
146c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
146d0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 ed. ^(By default
146e0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 , URI handling i
146f0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 s globally.** di
14700 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 sabled. The defa
14710 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 ult value may be
14720 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 changed by comp
14730 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a iling with the.*
14740 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 * [SQLITE_USE_UR
14750 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 I] symbol define
14760 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d.)^.**.** [[SQL
14770 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 ITE_CONFIG_COVER
14780 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d ING_INDEX_SCAN]]
14790 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
147a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
147b0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 X_SCAN.** <dd>^T
147c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
147d0 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 a single intege
147e0 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 r argument which
147f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
14800 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 as.** a boolean
14810 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 in order to enab
14820 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
14830 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e e use of coverin
14840 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a g indices for.**
14850 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e full table scan
14860 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f s in the query o
14870 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20 ptimizer. ^The
14880 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
14890 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a is determined.**
148a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
148b0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 ALLOW_COVERING_I
148c0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 NDEX_SCAN] compi
148d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
148e0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 or is "on".** if
148f0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 that compile-ti
14900 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 me option is omi
14910 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 tted..** The abi
14920 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 lity to disable
14930 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 the use of cover
14940 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 ing indices for
14950 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 full table scans
14960 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 .** is because s
14970 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ome incorrectly
14980 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 coded legacy app
14990 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lications might
149a0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 malfunction.** w
149b0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 hen the optimiza
149c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e tion is enabled.
149d0 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 Providing the
149e0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 ability to.** di
149f0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 sable the optimi
14a00 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 zation allows th
14a10 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 e older, buggy a
14a20 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
14a30 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f to work.** witho
14a40 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 ut change even w
14a50 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f ith newer versio
14a60 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a ns of SQLite..**
14a70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14a80 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 FIG_PCACHE]] [[S
14a90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
14aa0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e PCACHE]].** <dt>
14ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
14ac0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f ACHE and SQLITE_
14ad0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
14ae0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f .** <dd> These o
14af0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c ptions are obsol
14b00 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e ete and should n
14b10 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 ot be used by ne
14b20 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 w code..** They
14b30 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 are retained for
14b40 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
14b50 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 tibility but are
14b60 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 now no-ops..**
14b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
14b90 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 OG]].** <dt>SQLI
14ba0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
14bb0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
14bc0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
14bd0 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 lable if sqlite
14be0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
14bf0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
14c00 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 ENABLE_SQLLOG] p
14c10 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 re-processor mac
14c20 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 ro defined. The
14c30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 first argument s
14c40 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f hould.** be a po
14c50 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 inter to a funct
14c60 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 ion of type void
14c70 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
14c80 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 3*,const char*,
14c90 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 int)..** The sec
14ca0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 ond should be of
14cb0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 type (void*). T
14cc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 he callback is i
14cd0 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 nvoked by the li
14ce0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 brary.** in thre
14cf0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 e separate circu
14d00 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 mstances, identi
14d10 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 fied by the valu
14d20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a e passed as the.
14d30 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 ** fourth parame
14d40 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 ter. If the four
14d50 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
14d60 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 0, then the data
14d70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
14d80 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ** passed as the
14d90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
14da0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f has just been o
14db0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 pened. The third
14dc0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 argument.** poi
14dd0 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 nts to a buffer
14de0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
14df0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 ame of the main
14e00 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 database file. I
14e10 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 f the.** fourth
14e20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 parameter is 1,
14e30 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 then the SQL sta
14e40 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 tement that the
14e50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a third parameter.
14e60 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 ** points to has
14e70 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 just been execu
14e80 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 ted. Or, if the
14e90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
14ea0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 is 2, then.** t
14eb0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 he connection be
14ec0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 ing passed as th
14ed0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
14ee0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 er is being clos
14ef0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 ed. The.** third
14f00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 parameter is pa
14f10 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 ssed NULL In thi
14f20 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d s case. An exam
14f30 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 ple of using thi
14f40 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 s.** configurati
14f50 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 on option can be
14f60 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 seen in the "te
14f70 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 st_sqllog.c" sou
14f80 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 rce file in.** t
14f90 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c he canonical SQL
14fa0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e ite source tree.
14fb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
14fc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
14fd0 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 _SIZE]].** <dt>S
14fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
14ff0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 P_SIZE.** <dd>^S
15000 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
15010 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f P_SIZE takes two
15020 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
15030 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 (sqlite3_int64)
15040 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 values.** that a
15050 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d re the default m
15060 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 map size limit (
15070 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 the default sett
15080 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 ing for.** [PRAG
15090 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 MA mmap_size]) a
150a0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 nd the maximum a
150b0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 llowed mmap size
150c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 limit..** ^The
150d0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
150e0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
150f0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 n by each databa
15100 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 se connection us
15110 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 ing.** either th
15120 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 e [PRAGMA mmap_s
15130 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 ize] command, or
15140 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a by using the.**
15150 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [SQLITE_FCNTL_M
15160 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 MAP_SIZE] file c
15170 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d ontrol. ^(The m
15180 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d aximum allowed m
15190 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e map size.** cann
151a0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 74 ot be changed at
151b0 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 run-time. Nor
151c0 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 may the maximum
151d0 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a allowed mmap siz
151e0 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20 e.** exceed the
151f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 compile-time max
15200 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 imum mmap size s
15210 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 et by the.** [SQ
15220 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 LITE_MAX_MMAP_SI
15230 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ZE] compile-time
15240 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 option.)^.** ^I
15250 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e f either argumen
15260 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e t to this option
15270 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
15280 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 en that argument
15290 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 is.** changed t
152a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 o its compile-ti
152b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a me default..**.*
152c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
152d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
152e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
152f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
15300 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 APSIZE.** <dd>^T
15310 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e his option is on
15320 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
15330 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
15340 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a ed for Windows.*
15350 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 * with the [SQLI
15360 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d TE_WIN32_MALLOC]
15370 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d pre-processor m
15380 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a acro defined..**
15390 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 SQLITE_CONFIG_W
153a0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 IN32_HEAPSIZE ta
153b0 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 kes a 32-bit uns
153c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 igned integer va
153d0 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 lue.** that spec
153e0 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 ifies the maximu
153f0 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 m size of the cr
15400 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c eated heap..** <
15410 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
15420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
15430 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
15440 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
15450 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
15460 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
15470 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
15480 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15490 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
154a0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
154b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
154c0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
154d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
154e0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
154f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
15500 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
15510 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
15520 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
15530 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
15540 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
15550 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
15560 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
15570 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15580 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
15590 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
155a0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
155b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
155c0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
155d0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
155e0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
155f0 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
15600 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15610 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
15620 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
15630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
15640 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
15650 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
15660 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
15670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15680 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
15690 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
156a0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
156b0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
156c0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
156d0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
156e0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
156f0 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
15700 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15710 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
15720 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
15730 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
15740 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
15750 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 14 /* no-op *
15760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15770 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
15780 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f E 15 /* no-o
15790 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c p */.#define SQL
157a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 ITE_CONFIG_LOG
157b0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 16 /* x
157c0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 Func, void* */.#
157d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
157e0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 NFIG_URI
157f0 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 17 /* int */.
15800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15810 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 ONFIG_PCACHE2
15820 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 18 /* sqlite
15830 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
15840 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
15850 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
15860 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 CACHE2 19 /*
15870 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
15880 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 ethods2* */.#def
15890 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
158a0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
158b0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 _SCAN 20 /* int
158c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
158d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
158e0 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 21 /* xS
158f0 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a qllog, void* */.
15900 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15910 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 ONFIG_MMAP_SIZE
15920 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 22 /* sqlite
15930 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 3_int64, sqlite3
15940 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e _int64 */.#defin
15950 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15960 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 WIN32_HEAPSIZE
15970 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 23 /* int n
15980 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 Byte */../*.** C
15990 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 API3REF: Databas
159a0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e e Connection Con
159b0 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f figuration Optio
159c0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 ns.**.** These c
159d0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
159e0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
159f0 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
15a00 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
15a10 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
15a20 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
15a30 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
15a40 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
15a50 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a )] interface..**
15a60 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 .** New configur
15a70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 ation options ma
15a80 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
15a90 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
15aa0 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 SQLite..** Exis
15ab0 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 ting configurati
15ac0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 on options might
15ad0 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 be discontinued
15ae0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a . Applications.
15af0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 ** should check
15b00 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 the return code
15b10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 from [sqlite3_db
15b20 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 _config()] to ma
15b30 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 ke sure that.**
15b40 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e the call worked.
15b50 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ^The [sqlite3_
15b60 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
15b70 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 erface will retu
15b80 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f rn a.** non-zero
15b90 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 [error code] if
15ba0 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 a discontinued
15bb0 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 or unsupported c
15bc0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
15bd0 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 ion.** is invoke
15be0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a d..**.** <dl>.**
15bf0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
15c00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f NFIG_LOOKASIDE</
15c10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
15c20 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
15c30 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 hree additional
15c40 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
15c50 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a etermine the .**
15c60 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f [lookaside memo
15c70 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f ry allocator] co
15c80 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 nfiguration for
15c90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
15ca0 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 nnection]..** ^T
15cb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
15cc0 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 t (the third par
15cd0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
15ce0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
15cf0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
15d00 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 to a memory buff
15d10 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f er to use for lo
15d20 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a okaside memory..
15d30 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
15d40 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 gument after the
15d50 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
15d60 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a _LOOKASIDE verb.
15d70 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 ** may be NULL i
15d80 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c n which case SQL
15d90 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 ite will allocat
15da0 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 e the.** lookasi
15db0 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 de buffer itself
15dc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
15dd0 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 malloc()]. ^The
15de0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
15df0 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f is the.** size o
15e00 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 f each lookaside
15e10 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e buffer slot. ^
15e20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
15e30 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 nt is the number
15e40 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 of.** slots. T
15e50 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 he size of the b
15e60 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 uffer in the fir
15e70 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
15e80 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e be greater than
15e90 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 .** or equal to
15ea0 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 the product of t
15eb0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 he second and th
15ec0 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 ird arguments.
15ed0 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 The buffer.** mu
15ee0 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f st be aligned to
15ef0 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 an 8-byte bound
15f00 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 ary. ^If the se
15f10 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
15f20 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e .** SQLITE_DBCON
15f30 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 FIG_LOOKASIDE is
15f40 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 not a multiple
15f50 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 of 8, it is inte
15f60 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 rnally.** rounde
15f70 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 d down to the ne
15f80 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 xt smaller multi
15f90 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 ple of 8. ^(The
15fa0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
15fb0 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 y.** configurati
15fc0 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 on for a databas
15fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e e connection can
15fe0 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 only be changed
15ff0 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f when that.** co
16000 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 nnection is not
16010 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 currently using
16020 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
16030 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f , or in other wo
16040 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 rds.** when the
16050 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 "current value"
16060 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
16070 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 sqlite3_db_statu
16080 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e s](D,[SQLITE_CON
16090 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e FIG_LOOKASIDE],.
160a0 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 ..) is zero..**
160b0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 Any attempt to c
160c0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
160d0 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 ide memory confi
160e0 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f guration when lo
160f0 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 okaside.** memor
16100 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 y is in use leav
16110 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 es the configura
16120 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 tion unchanged a
16130 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b nd returns .** [
16140 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c SQLITE_BUSY].)^<
16150 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
16160 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
16170 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a NABLE_FKEY</dt>.
16180 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
16190 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
161a0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
161b0 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e e the enforcemen
161c0 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e t of.** [foreign
161d0 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 key constraints
161e0 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 ]. There should
161f0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
16200 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
16210 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
16220 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
16230 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
16240 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 disable FK enfor
16250 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 cement,.** posit
16260 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b ive to enable FK
16270 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 enforcement or
16280 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
16290 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
162a0 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 .** unchanged.
162b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
162c0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
162d0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
162e0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
162f0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
16300 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
16310 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 her FK enforceme
16320 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a nt is off or on.
16330 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 ** following thi
16340 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 s call. The sec
16350 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ond parameter ma
16360 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e y be a NULL poin
16370 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 ter, in.** which
16380 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 case the FK enf
16390 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 orcement setting
163a0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 is not reported
163b0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a back. </dd>.**.
163c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
163d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 CONFIG_ENABLE_TR
163e0 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 IGGER</dt>.** <d
163f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
16400 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
16410 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 e or disable [CR
16420 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
16430 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 riggers]..** The
16440 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f re should be two
16450 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 additional argu
16460 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 ments..** The fi
16470 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
16480 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
16490 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
164a0 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f triggers,.** po
164b0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
164c0 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 triggers or neg
164d0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 ative to leave t
164e0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 he setting uncha
164f0 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 nged..** The sec
16500 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
16510 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
16520 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 integer into wh
16530 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 ich.** is writte
16540 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 n 0 or 1 to indi
16550 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 cate whether tri
16560 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c ggers are disabl
16570 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a ed or enabled.**
16580 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
16590 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
165a0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
165b0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
165c0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
165d0 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 ase the trigger
165e0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
165f0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
16600 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a dd>.**.** </dl>.
16610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16620 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
16630 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 20 SIDE 1001
16640 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e /* void* int in
16650 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
16660 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
16670 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 BLE_FKEY 100
16680 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2 /* int int* *
16690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
166a0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
166b0 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 20 _TRIGGER 1003
166c0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a /* int int* */..
166d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
166e0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
166f0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 le Extended Resu
16700 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e lt Codes.**.** ^
16710 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
16720 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
16730 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 s() routine enab
16740 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
16750 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 the.** [extended
16760 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 result codes] f
16770 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 eature of SQLite
16780 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 . ^The extended
16790 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 result.** codes
167a0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
167b0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 default for hist
167c0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 orical compatibi
167d0 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c lity..*/.int sql
167e0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
167f0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
16800 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
16810 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16820 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
16830 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 wid.**.** ^Each
16840 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 entry in most SQ
16850 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 Lite tables (exc
16860 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 ept for [WITHOUT
16870 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a ROWID] tables).
16880 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 ** has a unique
16890 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 64-bit signed.**
168a0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c integer key cal
168b0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c led the [ROWID |
168c0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 "rowid"]. ^The
168d0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 rowid is always
168e0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 available.** as
168f0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f an undeclared co
16900 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 lumn named ROWID
16910 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 , OID, or _ROWID
16920 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f _ as long as tho
16930 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 se.** names are
16940 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 not also used by
16950 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c explicitly decl
16960 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 ared columns. ^I
16970 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 f.** the table h
16980 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 as a column of t
16990 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 ype [INTEGER PRI
169a0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 MARY KEY] then t
169b0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 hat column.** is
169c0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 another alias f
169d0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a or the rowid..**
169e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
169f0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
16a00 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 id(D) interface
16a10 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 returns the [row
16a20 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d id] of the .** m
16a30 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 ost recent succe
16a40 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 ssful [INSERT] i
16a50 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c nto a rowid tabl
16a60 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 e or [virtual ta
16a70 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 ble].** on datab
16a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 ase connection D
16a90 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e ..** ^Inserts in
16aa0 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 to [WITHOUT ROWI
16ab0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f D] tables are no
16ac0 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e t recorded..** ^
16ad0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c If no successful
16ae0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 [INSERT]s into
16af0 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 rowid tables.**
16b00 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 have ever occurr
16b10 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 ed on the databa
16b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c se connection D,
16b30 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 .** then sqlite
16b40 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
16b50 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a wid(D) returns z
16b60 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 ero..**.** ^(If
16b70 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 an [INSERT] occu
16b80 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 rs within a trig
16b90 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 ger or within a
16ba0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a [virtual table].
16bb0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 ** method, then
16bc0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c this routine wil
16bd0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f l return the [ro
16be0 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 wid] of the inse
16bf0 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c rted.** row as l
16c00 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67 ong as the trigg
16c10 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 er or virtual ta
16c20 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 ble method is ru
16c30 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e nning..** But on
16c40 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f ce the trigger o
16c50 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
16c60 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 method ends, the
16c70 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
16c80 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 .** by this rout
16c90 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 ine reverts to w
16ca0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 hat it was befor
16cb0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 e the trigger or
16cc0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c virtual.** tabl
16cd0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 e method began.)
16ce0 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 ^.**.** ^An [INS
16cf0 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 ERT] that fails
16d00 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 due to a constra
16d10 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 int violation is
16d20 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 not a.** succes
16d30 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e sful [INSERT] an
16d40 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 d does not chang
16d50 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 e the value retu
16d60 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 rned by this.**
16d70 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 routine. ^Thus
16d80 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 INSERT OR FAIL,
16d90 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 INSERT OR IGNORE
16da0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c , INSERT OR ROLL
16db0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 BACK,.** and INS
16dc0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b ERT OR ABORT mak
16dd0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 e no changes to
16de0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
16df0 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 of this.** rout
16e00 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 ine when their i
16e10 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 nsertion fails.
16e20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f ^(When INSERT O
16e30 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 R REPLACE.** enc
16e40 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 ounters a constr
16e50 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 aint violation,
16e60 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c it does not fail
16e70 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 . The.** INSERT
16e80 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f continues to co
16e90 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 mpletion after d
16ea0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 eleting rows tha
16eb0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 t caused.** the
16ec0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c constraint probl
16ed0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 em so INSERT OR
16ee0 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 REPLACE will alw
16ef0 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 ays change.** th
16f00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
16f10 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
16f20 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 .)^.**.** ^For t
16f30 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 he purposes of t
16f40 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 his routine, an
16f50 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 [INSERT] is cons
16f60 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 idered to.** be
16f70 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 successful even
16f80 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75 if it is subsequ
16f90 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 ently rolled bac
16fa0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 k..**.** This fu
16fb0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 nction is access
16fc0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 ible to SQL stat
16fd0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a ements via the.*
16fe0 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 * [last_insert_r
16ff0 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 owid() SQL funct
17000 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 ion]..**.** If a
17010 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
17020 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 performs a new
17030 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 [INSERT] on the
17040 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 same.** database
17050 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c connection whil
17060 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c e the [sqlite3_l
17070 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
17080 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ()].** function
17090 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 is running and t
170a0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 hus changes the
170b0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
170c0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 id],.** then the
170d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
170e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 by [sqlite3_last
170f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d _insert_rowid()]
17100 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 is.** unpredict
17110 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e able and might n
17120 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 ot equal either
17130 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e the old or the n
17140 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 ew.** last inser
17150 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 t [rowid]..*/.sq
17160 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
17170 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
17180 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b rowid(sqlite3*);
17190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
171a0 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 : Count The Numb
171b0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 er Of Rows Modif
171c0 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ied.**.** ^This
171d0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
171e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 the number of d
171f0 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 atabase rows tha
17200 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a t were changed.*
17210 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 * or inserted or
17220 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 deleted by the
17230 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f most recently co
17240 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 mpleted SQL stat
17250 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 ement.** on the
17260 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
17270 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 tion] specified
17280 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 by the first par
17290 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c ameter..** ^(Onl
172a0 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 y changes that a
172b0 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 re directly spec
172c0 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e ified by the [IN
172d0 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c SERT], [UPDATE],
172e0 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 .** or [DELETE]
172f0 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f statement are co
17300 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 unted. Auxiliar
17310 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 y changes caused
17320 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 by.** triggers
17330 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 or [foreign key
17340 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 actions] are not
17350 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 counted.)^ Use
17360 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
17370 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d total_changes()]
17380 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e function to fin
17390 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 d the total numb
173a0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a er of changes.**
173b0 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 including chang
173c0 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 es caused by tri
173d0 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 ggers and foreig
173e0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a n key actions..*
173f0 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f *.** ^Changes to
17400 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 a view that are
17410 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e simulated by an
17420 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
17430 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 gger].** are not
17440 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 counted. Only
17450 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 real table chang
17460 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a es are counted..
17470 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 **.** ^(A "row c
17480 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e hange" is a chan
17490 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 ge to a single r
174a0 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 ow of a single t
174b0 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 able.** caused b
174c0 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c y an INSERT, DEL
174d0 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 ETE, or UPDATE s
174e0 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 tatement. Rows
174f0 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e that.** are chan
17500 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 ged as side effe
17510 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d cts of [REPLACE]
17520 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
17530 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 lution,.** rollb
17540 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 ack, ABORT proce
17550 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 ssing, [DROP TAB
17560 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f LE], or by any o
17570 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 ther.** mechanis
17580 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 ms do not count
17590 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 as direct row ch
175a0 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 anges.)^.**.** A
175b0 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 "trigger contex
175c0 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 t" is a scope of
175d0 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 execution that
175e0 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e begins and.** en
175f0 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 ds with the scri
17600 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 pt of a [CREATE
17610 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
17620 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c r]. .** Most SQL
17630 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a statements are.
17640 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 ** evaluated out
17650 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 side of any trig
17660 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 ger. This is th
17670 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a e "top level".**
17680 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 trigger context
17690 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 . If a trigger
176a0 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 fires from the t
176b0 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e op level, a.** n
176c0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 ew trigger conte
176d0 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f xt is entered fo
176e0 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f r the duration o
176f0 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 f that one.** tr
17700 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 igger. Subtrigg
17710 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f ers create subco
17720 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 ntexts for their
17730 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a duration..**.**
17740 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 ^Calling [sqlit
17750 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 e3_exec()] or [s
17760 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 qlite3_step()] r
17770 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a ecursively does.
17780 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 ** not create a
17790 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 new trigger cont
177a0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ext..**.** ^This
177b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
177c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
177d0 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 direct row chang
177e0 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 es in the.** mos
177f0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c t recent INSERT,
17800 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
17810 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
17820 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 hin the same.**
17830 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e trigger context.
17840 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 .**.** ^Thus, wh
17850 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 en called from t
17860 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 he top level, th
17870 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
17880 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 rns the.** numbe
17890 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 r of changes in
178a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
178b0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
178c0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
178d0 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 t also occurred
178e0 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c at the top level
178f0 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 . ^(Within the
17900 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 body of a trigge
17910 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 r,.** the sqlite
17920 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 3_changes() inte
17930 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c rface can be cal
17940 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 led to find the
17950 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
17960 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 nges in the most
17970 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 recently comple
17980 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ted INSERT, UPDA
17990 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
179a0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
179b0 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 n the body of th
179c0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a e same trigger..
179d0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 ** However, the
179e0 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 number returned
179f0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
17a00 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 changes.** caus
17a10 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 ed by subtrigger
17a20 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 s since those ha
17a30 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e ve their own con
17a40 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 text.)^.**.** Se
17a50 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
17a60 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
17a70 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
17a80 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
17a90 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
17aa0 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 nd the [changes(
17ab0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
17ac0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
17ad0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
17ae0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
17af0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
17b00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
17b10 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e le [sqlite3_chan
17b20 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e ges()] is runnin
17b30 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 g then the value
17b40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 returned.** is
17b50 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e unpredictable an
17b60 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c d not meaningful
17b70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
17b80 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
17b90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
17ba0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
17bb0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
17bc0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 ed.**.** ^This f
17bd0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
17be0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
17bf0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 w changes caused
17c00 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a by [INSERT],.**
17c10 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 [UPDATE] or [DE
17c20 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 LETE] statements
17c30 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 since the [data
17c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
17c50 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 was opened..**
17c60 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 ^(The count retu
17c70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
17c80 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 total_changes()
17c90 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 includes all cha
17ca0 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c nges.** from all
17cb0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
17cc0 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 | trigger] cont
17cd0 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 exts and changes
17ce0 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 made by.** [for
17cf0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
17d00 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 ]. However,.** t
17d10 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f he count does no
17d20 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
17d30 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d s used to implem
17d40 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f ent [REPLACE] co
17d50 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f nstraints,.** do
17d60 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 rollbacks or AB
17d70 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 ORT processing,
17d80 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 or [DROP TABLE]
17d90 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 processing. The
17da0 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e .** count does n
17db0 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 ot include rows
17dc0 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 of views that fi
17dd0 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f re an [INSTEAD O
17de0 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 F trigger],.** t
17df0 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 hough if the INS
17e00 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 TEAD OF trigger
17e10 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 makes changes of
17e20 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 its own, those
17e30 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 changes .** are
17e40 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 counted.)^.** ^T
17e50 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c he sqlite3_total
17e60 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 _changes() funct
17e70 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 ion counts the c
17e80 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 hanges as soon a
17e90 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 s.** the stateme
17ea0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 nt that makes th
17eb0 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 em is completed
17ec0 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d (when the statem
17ed0 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 ent handle.** is
17ee0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 passed to [sqli
17ef0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
17f00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
17f10 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 e()])..**.** See
17f20 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 also the [sqlit
17f30 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e e3_changes()] in
17f40 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
17f50 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
17f60 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
17f70 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 [total_changes()
17f80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a SQL function]..
17f90 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 **.** If a separ
17fa0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 ate thread makes
17fb0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 changes on the
17fc0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f same database co
17fd0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c nnection.** whil
17fe0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c e [sqlite3_total
17ff0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 _changes()] is r
18000 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 unning then the
18010 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 value.** returne
18020 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 d is unpredictab
18030 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 le and not meani
18040 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ngful..*/.int sq
18050 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e lite3_total_chan
18060 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
18070 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18080 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 Interrupt A Long
18090 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a -Running Query.*
180a0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
180b0 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 ion causes any p
180c0 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 ending database
180d0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f operation to abo
180e0 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e rt and.** return
180f0 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 at its earliest
18100 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 opportunity. Th
18110 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 is routine is ty
18120 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 pically.** calle
18130 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f d in response to
18140 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 a user action s
18150 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 uch as pressing
18160 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 "Cancel".** or C
18170 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 trl-C where the
18180 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e user wants a lon
18190 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f g query operatio
181a0 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d n to halt.** imm
181b0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ediately..**.**
181c0 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 ^It is safe to c
181d0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
181e0 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 from a thread d
181f0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 ifferent from th
18200 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 e.** thread that
18210 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 is currently ru
18220 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 nning the databa
18230 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 se operation. B
18240 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 ut it.** is not
18250 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
18260 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
18270 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
18280 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 ction] that.** i
18290 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 s closed or migh
182a0 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 t close before s
182b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
182c0 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a () returns..**.*
182d0 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 * ^If an SQL ope
182e0 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e ration is very n
182f0 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 early finished a
18300 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a t the time when.
18310 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 ** sqlite3_inter
18320 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 rupt() is called
18330 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 , then it might
18340 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f not have an oppo
18350 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 rtunity.** to be
18360 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 interrupted and
18370 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 might continue
18380 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a to completion..*
18390 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 *.** ^An SQL ope
183a0 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 ration that is i
183b0 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 nterrupted will
183c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 return [SQLITE_I
183d0 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 NTERRUPT]..** ^I
183e0 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 f the interrupte
183f0 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 d SQL operation
18400 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 is an INSERT, UP
18410 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a DATE, or DELETE.
18420 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 ** that is insid
18430 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 e an explicit tr
18440 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 ansaction, then
18450 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 the entire trans
18460 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 action.** will b
18470 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 e rolled back au
18480 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a tomatically..**.
18490 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
184a0 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c interrupt(D) cal
184b0 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 l is in effect u
184c0 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 ntil all current
184d0 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 ly running.** SQ
184e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 L statements on
184f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
18500 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 tion] D complete
18510 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 . ^Any new SQL
18520 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
18530 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
18540 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
18550 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
18560 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 l and before the
18570 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 .** running sta
18580 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 tements reaches
18590 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 zero are interru
185a0 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 pted as if they
185b0 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e had been.** runn
185c0 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 ing prior to the
185d0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
185e0 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 pt() call. ^New
185f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a SQL statements.
18600 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 ** that are star
18610 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 ted after the ru
18620 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 nning statement
18630 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 count reaches ze
18640 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 ro are.** not ef
18650 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 fected by the sq
18660 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
18670 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f )..** ^A call to
18680 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
18690 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 pt(D) that occur
186a0 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 s when there are
186b0 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 no running.** S
186c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 QL statements is
186d0 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 a no-op and has
186e0 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 no effect on SQ
186f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
18700 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
18710 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 after the sqlit
18720 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
18730 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a all returns..**.
18740 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 ** If the databa
18750 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
18760 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 oses while [sqli
18770 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d te3_interrupt()]
18780 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 .** is running t
18790 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 hen bad things w
187a0 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 ill likely happe
187b0 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 n..*/.void sqlit
187c0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c e3_interrupt(sql
187d0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
187e0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 API3REF: Determi
187f0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 ne If An SQL Sta
18800 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 tement Is Comple
18810 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 te.**.** These r
18820 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 outines are usef
18830 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e ul during comman
18840 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 d-line input to
18850 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 determine if the
18860 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e .** currently en
18870 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 tered text seems
18880 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c to form a compl
18890 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
188a0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 t or.** if addit
188b0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e ional input is n
188c0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e eeded before sen
188d0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e ding the text in
188e0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 to.** SQLite for
188f0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 parsing. ^Thes
18900 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
18910 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 n 1 if the input
18920 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 string.** appea
18930 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c rs to be a compl
18940 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ete SQL statemen
18950 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 t. ^A statement
18960 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 is judged to be
18970 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 .** complete if
18980 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 it ends with a s
18990 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 emicolon token a
189a0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 nd is not a pref
189b0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d ix of a.** well-
189c0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 formed CREATE TR
189d0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e IGGER statement.
189e0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 ^Semicolons th
189f0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 at are embedded
18a00 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 within.** string
18a10 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f literals or quo
18a20 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e ted identifier n
18a30 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 ames or comments
18a40 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 are not.** inde
18a50 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 pendent tokens (
18a60 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 they are part of
18a70 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 the token in wh
18a80 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 ich they are.**
18a90 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 embedded) and th
18aa0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 us do not count
18ab0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 as a statement t
18ac0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 erminator. ^Whi
18ad0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 tespace.** and c
18ae0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c omments that fol
18af0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 low the final se
18b00 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f micolon are igno
18b10 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 red..**.** ^Thes
18b20 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 e routines retur
18b30 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 n 0 if the state
18b40 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 ment is incomple
18b50 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 te. ^If a.** me
18b60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
18b70 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 fails, then SQLI
18b80 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 TE_NOMEM is retu
18b90 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rned..**.** ^The
18ba0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e se routines do n
18bb0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c ot parse the SQL
18bc0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 statements thus
18bd0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 .** will not det
18be0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c ect syntacticall
18bf0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e y incorrect SQL.
18c00 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 .**.** ^(If SQLi
18c10 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 te has not been
18c20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e initialized usin
18c30 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 g [sqlite3_initi
18c40 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a alize()] prior .
18c50 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 ** to invoking s
18c60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
18c70 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 6() then sqlite3
18c80 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
18c90 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f invoked.** auto
18ca0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c matically by sql
18cb0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
18cc0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 ). If that init
18cd0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 ialization fails
18ce0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 ,.** then the re
18cf0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
18d00 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
18d10 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 16() will be non
18d20 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c -zero.** regardl
18d30 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
18d40 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 r not the input
18d50 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e SQL is complete.
18d60 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 )^.**.** The inp
18d70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ut to [sqlite3_c
18d80 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 omplete()] must
18d90 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e be a zero-termin
18da0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 ated.** UTF-8 st
18db0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ring..**.** The
18dc0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
18dd0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 3_complete16()]
18de0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 must be a zero-t
18df0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 erminated.** UTF
18e00 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 -16 string in na
18e10 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
18e20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
18e30 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 complete(const c
18e40 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 har *sql);.int s
18e50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
18e60 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
18e70 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
18e80 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
18e90 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
18ea0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
18eb0 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 rrors.**.** ^The
18ec0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
18ed0 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 ndler(D,X,P) rou
18ee0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c tine sets a call
18ef0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a back function X.
18f00 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 ** that might be
18f10 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 invoked with ar
18f20 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 gument P wheneve
18f30 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 r.** an attempt
18f40 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 is made to acces
18f50 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 s a database tab
18f60 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 le associated wi
18f70 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 th.** [database
18f80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 connection] D wh
18f90 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 en another threa
18fa0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 d.** or process
18fb0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f has the table lo
18fc0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c cked..** The sql
18fd0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
18fe0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 r() interface is
18ff0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 used to impleme
19000 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nt.** [sqlite3_b
19010 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 usy_timeout()] a
19020 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f nd [PRAGMA busy_
19030 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 timeout]..**.**
19040 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
19050 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 lback is NULL, t
19060 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 hen [SQLITE_BUSY
19070 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
19080 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 RR_BLOCKED].** i
19090 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
190a0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f iately upon enco
190b0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 untering the loc
190c0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 k. ^If the busy
190d0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
190e0 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 not NULL, then t
190f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 he callback migh
19100 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 t be invoked wit
19110 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e h two arguments.
19120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
19130 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
19140 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
19150 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
19160 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 void* pointer wh
19170 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 ich.** is the th
19180 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
19190 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
191a0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 dler(). ^The se
191b0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
191c0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
191d0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 dler callback is
191e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 the number of t
191f0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 imes that the bu
19200 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a sy handler has.*
19210 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 * been invoked f
19220 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b or the same lock
19230 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
19240 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c the.** busy call
19250 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 back returns 0,
19260 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e then no addition
19270 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 al attempts are
19280 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 made to.** acces
19290 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
192a0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d nd [SQLITE_BUSY]
192b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
192c0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 R_BLOCKED] is re
192d0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 turned.** to the
192e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a application..**
192f0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
19300 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
19310 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 ro, then another
19320 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d attempt.** is m
19330 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 ade to access th
19340 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 e database and t
19350 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 he cycle repeats
19360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 ..**.** The pres
19370 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 ence of a busy h
19380 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 andler does not
19390 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 guarantee that i
193a0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
193b0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 d.** when there
193c0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 is lock contenti
193d0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 on. ^If SQLite d
193e0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 etermines that i
193f0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
19400 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c .** handler coul
19410 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 d result in a de
19420 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 adlock, it will
19430 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 go ahead and ret
19440 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
19450 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ].** or [SQLITE_
19460 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 74 IOERR_BLOCKED] t
19470 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
19480 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 n instead of inv
19490 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 oking the .** bu
194a0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
194b0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
194c0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
194d0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
194e0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
194f0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
19500 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
19510 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
19520 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
19530 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
19540 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
19550 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
19560 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
19570 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
19580 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
19590 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
195a0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
195b0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
195c0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
195d0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
195e0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
195f0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
19600 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
19610 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
19620 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
19630 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
19640 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
19650 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
19660 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
19670 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
19680 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
19690 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
196a0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
196b0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
196c0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
196d0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
196e0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
196f0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
19700 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
19710 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
19720 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 roceed..**.** ^T
19730 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
19740 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
19750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ..**.** ^The [SQ
19760 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 LITE_BUSY] error
19770 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f is converted to
19780 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
19790 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 LOCKED].** when
197a0 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 SQLite is in the
197b0 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 middle of a lar
197c0 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 ge transaction w
197d0 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 here all the.**
197e0 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 changes will not
197f0 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e fit into the in
19800 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 -memory cache.
19810 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 SQLite will.** a
19820 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 lready hold a RE
19830 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 SERVED lock on t
19840 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
19850 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a , but it needs.*
19860 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 * to promote thi
19870 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 s lock to EXCLUS
19880 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 IVE so that it c
19890 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a an spill cache.*
198a0 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 * pages into the
198b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
198c0 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 ithout harm to c
198d0 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 oncurrent.** rea
198e0 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 ders. ^If it is
198f0 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f unable to promo
19900 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 te the lock, the
19910 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a n the in-memory.
19920 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 ** cache will be
19930 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f left in an inco
19940 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 nsistent state a
19950 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a nd so the error.
19960 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f ** code is promo
19970 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c ted from the rel
19980 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b atively benign [
19990 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a SQLITE_BUSY] to.
199a0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 ** the more seve
199b0 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 re [SQLITE_IOERR
199c0 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 _BLOCKED]. ^Thi
199d0 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f s error code pro
199e0 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 motion.** forces
199f0 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f an automatic ro
19a00 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 llback of the ch
19a10 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a anges. See the.
19a20 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 ** <a href="/cvs
19a30 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 trac/wiki?p=Corr
19a40 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
19a50 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f usyError">.** Co
19a60 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e rruptionFollowin
19a70 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 gBusyError</a> w
19a80 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 iki page for a d
19a90 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 iscussion of why
19aa0 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f .** this is impo
19ab0 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 rtant..**.** ^(T
19ac0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 here can only be
19ad0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 a single busy h
19ae0 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 andler defined f
19af0 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 or each.** [data
19b00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
19b10 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 . Setting a new
19b20 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c busy handler cl
19b30 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 ears any.** prev
19b40 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c iously set handl
19b50 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 er.)^ ^Note tha
19b60 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
19b70 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
19b80 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 )].** or evaluat
19b90 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 ing [PRAGMA busy
19ba0 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c _timeout=N] will
19bb0 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 change the.** b
19bc0 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 usy handler and
19bd0 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 thus clear any p
19be0 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 reviously set bu
19bf0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a sy handler..**.*
19c00 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 * The busy callb
19c10 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 ack should not t
19c20 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 ake any actions
19c30 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 which modify the
19c40 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
19c50 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 nection that inv
19c60 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 oked the busy ha
19c70 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 ndler. In other
19c80 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 words,.** the b
19c90 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e usy handler is n
19ca0 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 ot reentrant. A
19cb0 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a ny such actions.
19cc0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 ** result in und
19cd0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
19ce0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 .** .** A busy h
19cf0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 andler must not
19d00 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
19d10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
19d20 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 or [prepared st
19d30 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e atement] that in
19d40 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
19d50 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 andler..*/.int s
19d60 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
19d70 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e ler(sqlite3*, in
19d80 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c t(*)(void*,int),
19d90 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
19da0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
19db0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a Busy Timeout.**.
19dc0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
19dd0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 sets a [sqlite3
19de0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 _busy_handler |
19df0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 busy handler] th
19e00 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 at sleeps.** for
19e10 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f a specified amo
19e20 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e unt of time when
19e30 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b a table is lock
19e40 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 ed. ^The handle
19e50 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 r.** will sleep
19e60 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 multiple times u
19e70 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d ntil at least "m
19e80 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 s" milliseconds
19e90 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 of sleeping.** h
19ea0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e ave accumulated.
19eb0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 ^After at leas
19ec0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
19ed0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c nds of sleeping,
19ee0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 .** the handler
19ef0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 returns 0 which
19f00 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f causes [sqlite3_
19f10 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 step()] to retur
19f20 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 n.** [SQLITE_BUS
19f30 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f Y] or [SQLITE_IO
19f40 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a ERR_BLOCKED]..**
19f50 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 .** ^Calling thi
19f60 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
19f70 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
19f80 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
19f90 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
19fa0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
19fb0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lers..**.** ^(Th
19fc0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
19fd0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
19fe0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
19ff0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
1a000 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1a010 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f any any given mo
1a020 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 ment. If anothe
1a030 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a r busy handler.*
1a040 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 * was defined (
1a050 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 using [sqlite3_b
1a060 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 usy_handler()])
1a070 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
1a080 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
1a090 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 , that other bus
1a0a0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 y handler is cle
1a0b0 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 ared.)^.**.** Se
1a0c0 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 e also: [PRAGMA
1a0d0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a busy_timeout].*
1a0e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 /.int sqlite3_bu
1a0f0 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 sy_timeout(sqlit
1a100 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f e3*, int ms);../
1a110 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1a120 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 onvenience Routi
1a130 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 nes For Running
1a140 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 Queries.**.** Th
1a150 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 is is a legacy i
1a160 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 nterface that is
1a170 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 preserved for b
1a180 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
1a190 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f bility..** Use o
1a1a0 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
1a1b0 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e is not recommen
1a1c0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e ded..**.** Defin
1a1d0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 ition: A <b>resu
1a1e0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 lt table</b> is
1a1f0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 memory data stru
1a200 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 cture created by
1a210 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1a220 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e _get_table()] in
1a230 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 terface. A resu
1a240 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 lt table records
1a250 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 the.** complete
1a260 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 query results f
1a270 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 rom one or more
1a280 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 queries..**.** T
1a290 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 he table concept
1a2a0 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 ually has a numb
1a2b0 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 er of rows and c
1a2c0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 olumns. But.**
1a2d0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 these numbers ar
1a2e0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 e not part of th
1a2f0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
1a300 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a tself. These.**
1a310 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 numbers are obt
1a320 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 ained separately
1a330 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 . Let N be the
1a340 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a number of rows.*
1a350 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e * and M be the n
1a360 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
1a370 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
1a380 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 table is an arr
1a390 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
1a3a0 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
1a3b0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
1a3c0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e .** There are (N
1a3d0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
1a3e0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 n the array. Th
1a3f0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 e first M pointe
1a400 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a rs point.** to z
1a410 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
1a420 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e trings that con
1a430 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f tain the names o
1a440 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a f the columns..*
1a450 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
1a460 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e entries all poin
1a470 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c t to query resul
1a480 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 ts. NULL values
1a490 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 result.** in NU
1a4a0 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c LL pointers. Al
1a4b0 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 l other values a
1a4c0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d re in their UTF-
1a4d0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
1a4e0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 d.** string repr
1a4f0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 esentation as re
1a500 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1a510 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
1a520 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c ]..**.** A resul
1a530 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f t table might co
1a540 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 nsist of one or
1a550 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f more memory allo
1a560 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 cations..** It i
1a570 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 s not safe to pa
1a580 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ss a result tabl
1a590 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 e directly to [s
1a5a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
1a5b0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1a5c0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c e should be deal
1a5d0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 located using [s
1a5e0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1a5f0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 e()]..**.** ^(As
1a600 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
1a610 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
1a620 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
1a630 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
1a640 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
1a650 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1a660 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
1a670 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
1a680 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
1a690 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1a6a0 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
1a6b0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
1a6c0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
1a6d0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
1a6e0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
1a6f0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
1a700 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1a710 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
1a720 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
1a730 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
1a740 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
1a750 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
1a760 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
1a770 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
1a780 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
1a790 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
1a7a0 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
1a7b0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
1a7c0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
1a7d0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
1a7e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1a7f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1a800 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
1a810 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1a820 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
1a830 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
1a840 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
1a850 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
1a860 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1a870 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
1a880 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1a890 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
1a8a0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1a8b0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
1a8c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1a8d0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
1a8e0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
1a8f0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
1a900 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
1a910 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
1a920 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
1a930 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1a940 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 function evalua
1a950 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a tes one or more.
1a960 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
1a970 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 arated SQL state
1a980 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 ments in the zer
1a990 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
1a9a0 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 -8.** string of
1a9b0 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 its 2nd paramete
1a9c0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 r and returns a
1a9d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
1a9e0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
1a9f0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
1aa00 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
1aa10 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 After the appli
1aa20 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 cation has finis
1aa30 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 hed with the res
1aa40 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ult from sqlite3
1aa50 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a _get_table(),.**
1aa60 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 it must pass th
1aa70 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 e result table p
1aa80 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
1aa90 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
1aaa0 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 n order to.** re
1aab0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
1aac0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 that was malloc
1aad0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 ed. Because of
1aae0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b the way the.** [
1aaf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1ab00 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e ] happens within
1ab10 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1ab20 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e le(), the callin
1ab30 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 g.** function mu
1ab40 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
1ab50 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
1ab60 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
1ab70 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nly.** [sqlite3_
1ab80 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 free_table()] is
1ab90 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 able to release
1aba0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 the memory prop
1abb0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e erly and safely.
1abc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
1abd0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 e3_get_table() i
1abe0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
1abf0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 emented as a wra
1ac00 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
1ac10 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e sqlite3_exec()].
1ac20 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 The sqlite3_ge
1ac30 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e t_table() routin
1ac40 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 e does not have
1ac50 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 access.** to any
1ac60 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 internal data s
1ac70 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c tructures of SQL
1ac80 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e ite. It uses on
1ac90 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a ly the public.**
1aca0 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
1acb0 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 ed here. As a c
1acc0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f onsequence, erro
1acd0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e rs that occur in
1ace0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 the.** wrapper
1acf0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 layer outside of
1ad00 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 the internal [s
1ad10 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 qlite3_exec()] c
1ad20 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 all are not.** r
1ad30 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 eflected in subs
1ad40 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
1ad50 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
1ad60 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
1ad70 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f e3_errmsg()]..*/
1ad80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 .int sqlite3_get
1ad90 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 _table(. sqlite
1ada0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
1adb0 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
1adc0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
1add0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f har *zSql, /
1ade0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c * SQL to be eval
1adf0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 uated */. char
1ae00 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 ***pazResult,
1ae10 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 /* Results of t
1ae20 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e he query */. in
1ae30 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 t *pnRow,
1ae40 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 /* Number of
1ae50 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 result rows wri
1ae60 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 tten here */. i
1ae70 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 nt *pnColumn,
1ae80 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
1ae90 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 f result columns
1aea0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1aeb0 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d . char **pzErrm
1aec0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f sg /* Erro
1aed0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
1aee0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 re */.);.void sq
1aef0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
1af00 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b (char **result);
1af10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1af20 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 : Formatted Stri
1af30 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 ng Printing Func
1af40 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
1af50 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 e routines are w
1af60 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 ork-alikes of th
1af70 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d e "printf()" fam
1af80 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 ily of functions
1af90 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 .** from the sta
1afa0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
1afb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1afc0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e te3_mprintf() an
1afd0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e d sqlite3_vmprin
1afe0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 tf() routines wr
1aff0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 ite their.** res
1b000 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 ults into memory
1b010 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b obtained from [
1b020 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1b030 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 ]..** The string
1b040 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 s returned by th
1b050 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 ese two routines
1b060 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 should be.** re
1b070 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 leased by [sqlit
1b080 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f e3_free()]. ^Bo
1b090 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 th routines retu
1b0a0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 rn a.** NULL poi
1b0b0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 nter if [sqlite3
1b0c0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e _malloc()] is un
1b0d0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
1b0e0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 enough.** memor
1b0f0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 y to hold the re
1b100 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a sulting string..
1b110 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 **.** ^(The sqli
1b120 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 te3_snprintf() r
1b130 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 outine is simila
1b140 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 r to "snprintf()
1b150 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 " from.** the st
1b160 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 andard C library
1b170 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 . The result is
1b180 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1b190 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 e.** buffer supp
1b1a0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f lied as the seco
1b1b0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f nd parameter who
1b1c0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e se size is given
1b1d0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 by.** the first
1b1e0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 parameter. Note
1b1f0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 that the order
1b200 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 of the.** first
1b210 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 two parameters i
1b220 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 s reversed from
1b230 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 snprintf().)^ T
1b240 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 his is an.** his
1b250 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 torical accident
1b260 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 that cannot be
1b270 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 fixed without br
1b280 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 eaking.** backwa
1b290 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 rds compatibilit
1b2a0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 y. ^(Note also
1b2b0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 that sqlite3_snp
1b2c0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 rintf().** retur
1b2d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
1b2e0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 its buffer inste
1b2f0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 ad of the number
1b300 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 of.** character
1b310 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 s actually writt
1b320 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 en into the buff
1b330 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 er.)^ We admit
1b340 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 that.** the numb
1b350 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
1b360 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 written would b
1b370 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 e a more useful
1b380 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
1b390 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 but we cannot ch
1b3a0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ange the impleme
1b3b0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 ntation of sqlit
1b3c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1b3d0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 now without bre
1b3e0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c aking compatibil
1b3f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c ity..**.** ^As l
1b400 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 ong as the buffe
1b410 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 r size is greate
1b420 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c r than zero, sql
1b430 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1b440 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 ** guarantees th
1b450 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 at the buffer is
1b460 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 always zero-ter
1b470 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 minated. ^The f
1b480 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 irst.** paramete
1b490 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 r "n" is the tot
1b4a0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 al size of the b
1b4b0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 uffer, including
1b4c0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 space for.** th
1b4d0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
1b4e0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 r. So the longe
1b4f0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 st string that c
1b500 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 an be completely
1b510 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c .** written will
1b520 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 be n-1 characte
1b530 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 rs..**.** ^The s
1b540 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 qlite3_vsnprintf
1b550 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 () routine is a
1b560 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 varargs version
1b570 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
1b580 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ntf()..**.** The
1b590 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 se routines all
1b5a0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 implement some a
1b5b0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 dditional format
1b5c0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 ting.** options
1b5d0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 that are useful
1b5e0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 for constructing
1b5f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
1b600 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 .** All of the u
1b610 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f sual printf() fo
1b620 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 rmatting options
1b630 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 apply. In addi
1b640 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 tion, there.** i
1b650 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 s are "%q", "%Q"
1b660 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f , and "%z" optio
1b670 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ns..**.** ^(The
1b680 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %q option works
1b690 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 like %s in that
1b6a0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 it substitutes a
1b6b0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a nul-terminated.
1b6c0 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 ** string from t
1b6d0 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 he argument list
1b6e0 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 . But %q also d
1b6f0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 oubles every '\'
1b700 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 ' character..**
1b710 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 %q is designed f
1b720 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 or use inside a
1b730 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 string literal.)
1b740 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 ^ By doubling e
1b750 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 ach '\''.** char
1b760 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 acter it escapes
1b770 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 that character
1b780 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f and allows it to
1b790 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 be inserted int
1b7a0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e o.** the string.
1b7b0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 .**.** For examp
1b7c0 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 le, assume the s
1b7d0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a tring variable z
1b7e0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 Text contains te
1b7f0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a xt as follows:.*
1b800 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1b810 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 ><pre>.** char
1b820 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 *zText = "It's a
1b830 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a happy day!";.**
1b840 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1b850 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 ote>.**.** One c
1b860 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 an use this text
1b870 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 in an SQL state
1b880 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a ment as follows:
1b890 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1b8a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 te><pre>.** cha
1b8b0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 r *zSQL = sqlite
1b8c0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 3_mprintf("INSER
1b8d0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c T INTO table VAL
1b8e0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 UES('%q')", zTex
1b8f0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f t);.** sqlite3_
1b900 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 exec(db, zSQL, 0
1b910 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c , 0, 0);.** sql
1b920 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b ite3_free(zSQL);
1b930 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1b940 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 kquote>.**.** Be
1b950 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 cause the %q for
1b960 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 mat string is us
1b970 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 ed, the '\'' cha
1b980 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a racter in zText.
1b990 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e ** is escaped an
1b9a0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 d the SQL genera
1b9b0 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 ted is as follow
1b9c0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s:.**.** <blockq
1b9d0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 uote><pre>.** I
1b9e0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
1b9f0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 1 VALUES('It''s
1ba00 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a a happy day!').*
1ba10 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1ba20 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 uote>.**.** This
1ba30 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 is correct. Ha
1ba40 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 d we used %s ins
1ba50 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 tead of %q, the
1ba60 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a generated SQL.**
1ba70 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b would have look
1ba80 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a ed like this:.**
1ba90 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1baa0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
1bab0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
1bac0 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 UES('It's a happ
1bad0 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 y day!');.** </p
1bae0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1baf0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f .**.** This seco
1bb00 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e nd example is an
1bb10 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f SQL syntax erro
1bb20 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c r. As a general
1bb30 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 rule you should
1bb40 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 .** always use %
1bb50 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 q instead of %s
1bb60 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 when inserting t
1bb70 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e ext into a strin
1bb80 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a g literal..**.**
1bb90 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e ^(The %Q option
1bba0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 works like %q e
1bbb0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 xcept it also ad
1bbc0 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 ds single quotes
1bbd0 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f around.** the o
1bbe0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f utside of the to
1bbf0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 tal string. Add
1bc00 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 itionally, if th
1bc10 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 e parameter in t
1bc20 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c he.** argument l
1bc30 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ist is a NULL po
1bc40 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 inter, %Q substi
1bc50 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 tutes the text "
1bc60 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a NULL" (without.*
1bc70 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 * single quotes)
1bc80 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 .)^ So, for exa
1bc90 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 mple, one could
1bca0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 say:.**.** <bloc
1bcb0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1bcc0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 char *zSQL = sq
1bcd0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 lite3_mprintf("I
1bce0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 NSERT INTO table
1bcf0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 VALUES(%Q)", zT
1bd00 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 ext);.** sqlite
1bd10 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 3_exec(db, zSQL,
1bd20 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 0, 0, 0);.** s
1bd30 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c qlite3_free(zSQL
1bd40 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1bd50 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1bd60 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 The code above w
1bd70 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 ill render a cor
1bd80 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 rect SQL stateme
1bd90 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a nt in the zSQL.*
1bda0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 * variable even
1bdb0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 if the zText var
1bdc0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 iable is a NULL
1bdd0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
1bde0 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 (The "%z" format
1bdf0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b ting option work
1be00 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 s like "%s" but
1be10 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 with the.** addi
1be20 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 tion that after
1be30 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 the string has b
1be40 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 een read and cop
1be50 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ied into.** the
1be60 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 result, [sqlite3
1be70 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c _free()] is call
1be80 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 ed on the input
1be90 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 string.)^.*/.cha
1bea0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e r *sqlite3_mprin
1beb0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e tf(const char*,.
1bec0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 ..);.char *sqlit
1bed0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
1bee0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
1bef0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 );.char *sqlite3
1bf00 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
1bf10 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1bf20 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c ...);.char *sql
1bf30 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 ite3_vsnprintf(i
1bf40 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
1bf50 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
1bf60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1bf70 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
1bf80 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a on Subsystem.**.
1bf90 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
1bfa0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 re uses these th
1bfb0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
1bfc0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
1bfd0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
1bfe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
1bff0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
1c000 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
1c010 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
1c020 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
1c030 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
1c040 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
1c050 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
1c060 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
1c070 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
1c080 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
1c090 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
1c0a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1c0b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
1c0c0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
1c0d0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
1c0e0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
1c0f0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
1c100 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
1c110 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
1c120 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 er..** ^If sqlit
1c130 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
1c140 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
1c150 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
1c160 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
1c170 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
1c180 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 nter. ^If the p
1c190 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
1c1a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1c1b0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
1c1c0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
1c1d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
1c1e0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
1c1f0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 inter..**.** ^Ca
1c200 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 lling sqlite3_fr
1c210 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e ee() with a poin
1c220 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 ter previously r
1c230 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 eturned.** by sq
1c240 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f lite3_malloc() o
1c250 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1c260 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 c() releases tha
1c270 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 t memory so.** t
1c280 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 hat it might be
1c290 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 reused. ^The sq
1c2a0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 lite3_free() rou
1c2b0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d tine is.** a no-
1c2c0 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 op if is called
1c2d0 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e with a NULL poin
1c2e0 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 ter. Passing a
1c2f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
1c300 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 to sqlite3_free(
1c310 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 ) is harmless.
1c320 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 After being free
1c330 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f d, memory.** sho
1c340 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 uld neither be r
1c350 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e ead nor written.
1c360 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 Even reading p
1c370 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a reviously freed.
1c380 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 ** memory might
1c390 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d result in a segm
1c3a0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f entation fault o
1c3b0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1c3c0 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 rror..** Memory
1c3d0 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 corruption, a se
1c3e0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 gmentation fault
1c3f0 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 , or other sever
1c400 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 e error.** might
1c410 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 result if sqlit
1c420 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c e3_free() is cal
1c430 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e led with a non-N
1c440 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ULL pointer that
1c450 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 .** was not obta
1c460 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 ined from sqlite
1c470 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
1c480 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e lite3_realloc().
1c490 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c .**.** ^(The sql
1c4a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 ite3_realloc() i
1c4b0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
1c4c0 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a s to resize a.**
1c4d0 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c prior memory al
1c4e0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 location to be a
1c4f0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c t least N bytes,
1c500 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a where N is the.
1c510 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 ** second parame
1c520 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 ter. The memory
1c530 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 allocation to b
1c540 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 e resized is the
1c550 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
1c560 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 ter.)^ ^ If the
1c570 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1c580 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c to sqlite3_reall
1c590 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c oc().** is a NUL
1c5a0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 L pointer then i
1c5b0 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 ts behavior is i
1c5c0 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c dentical to call
1c5d0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ing.** sqlite3_m
1c5e0 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e alloc(N) where N
1c5f0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 is the second p
1c600 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1c610 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a te3_realloc()..*
1c620 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 * ^If the second
1c630 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1c640 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
1c650 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 is zero or.** ne
1c660 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 gative then the
1c670 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 behavior is exac
1c680 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 tly the same as
1c690 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
1c6a0 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 e3_free(P) where
1c6b0 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 P is the first
1c6c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
1c6d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
1c6e0 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c ** ^sqlite3_real
1c6f0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 loc() returns a
1c700 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
1c710 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
1c720 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 * of at least N
1c730 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 bytes in size or
1c740 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 NULL if suffici
1c750 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e ent memory is un
1c760 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 available..** ^I
1c770 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
1c780 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1c790 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
1c7a0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
1c7b0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1c7c0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
1c7d0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
1c7e0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
1c7f0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
1c800 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1c810 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 and the prior a
1c820 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 llocation is fre
1c830 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 ed..** ^If sqlit
1c840 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 e3_realloc() ret
1c850 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 urns NULL, then
1c860 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1c870 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 tion.** is not f
1c880 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 reed..**.** ^The
1c890 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 memory returned
1c8a0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c by sqlite3_mall
1c8b0 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 oc() and sqlite3
1c8c0 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 _realloc().** is
1c8d0 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 always aligned
1c8e0 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 to at least an 8
1c8f0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 byte boundary,
1c900 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 or to a.** 4 byt
1c910 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 e boundary if th
1c920 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 e [SQLITE_4_BYTE
1c930 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d _ALIGNED_MALLOC]
1c940 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a compile-time.**
1c950 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e option is used.
1c960 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 .**.** In SQLite
1c970 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 version 3.5.0 a
1c980 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 nd 3.5.1, it was
1c990 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 possible to def
1c9a0 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 ine.** the SQLIT
1c9b0 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c E_OMIT_MEMORY_AL
1c9c0 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 LOCATION which w
1c9d0 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 ould cause the b
1c9e0 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 uilt-in.** imple
1c9f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 mentation of the
1ca00 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 se routines to b
1ca10 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 e omitted. That
1ca20 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
1ca30 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 s no longer prov
1ca40 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c ided. Only buil
1ca50 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f t-in memory allo
1ca60 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 cators can be us
1ca70 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 ed..**.** Prior
1ca80 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f to SQLite versio
1ca90 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 n 3.7.10, the Wi
1caa0 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 ndows OS interfa
1cab0 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a ce layer called.
1cac0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 ** the system ma
1cad0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 lloc() and free(
1cae0 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 ) directly when
1caf0 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 converting.** fi
1cb00 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 lenames between
1cb10 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 the UTF-8 encodi
1cb20 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 ng used by SQLit
1cb30 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 e.** and whateve
1cb40 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 r filename encod
1cb50 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 ing is used by t
1cb60 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 he particular Wi
1cb70 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c ndows.** install
1cb80 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 ation. Memory a
1cb90 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 llocation errors
1cba0 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 were detected,
1cbb0 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 but.** they were
1cbc0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 reported back a
1cbd0 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 s [SQLITE_CANTOP
1cbe0 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 EN] or.** [SQLIT
1cbf0 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 E_IOERR] rather
1cc00 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d than [SQLITE_NOM
1cc10 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 EM]..**.** The p
1cc20 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 ointer arguments
1cc30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
1cc40 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
1cc50 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 3_realloc()].**
1cc60 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e must be either N
1cc70 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e ULL or else poin
1cc80 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 ters obtained fr
1cc90 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e om a prior.** in
1cca0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c vocation of [sql
1ccb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f ite3_malloc()] o
1ccc0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
1ccd0 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a oc()] that have.
1cce0 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 ** not yet been
1ccf0 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 released..**.**
1cd00 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
1cd10 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 must not read or
1cd20 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 write any part
1cd30 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 of.** a block of
1cd40 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 memory after it
1cd50 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 has been releas
1cd60 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
1cd70 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 ite3_free()] or
1cd80 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1cd90 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ()]..*/.void *sq
1cda0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 lite3_malloc(int
1cdb0 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 );.void *sqlite3
1cdc0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 _realloc(void*,
1cdd0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
1cde0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a e3_free(void*);.
1cdf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1ce00 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f Memory Allocato
1ce10 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a r Statistics.**.
1ce20 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 ** SQLite provid
1ce30 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 es these two int
1ce40 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f erfaces for repo
1ce50 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 rting on the sta
1ce60 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 tus.** of the [s
1ce70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1ce80 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
1ce90 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
1cea0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 _realloc()].** r
1ceb0 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 outines, which f
1cec0 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e orm the built-in
1ced0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1cee0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a on subsystem..**
1cef0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
1cf00 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
1cf10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1cf20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
1cf30 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 ytes.** of memor
1cf40 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 y currently outs
1cf50 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 tanding (malloce
1cf60 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 d but not freed)
1cf70 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 ..** ^The [sqlit
1cf80 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1cf90 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 ter()] routine r
1cfa0 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d eturns the maxim
1cfb0 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b um.** value of [
1cfc0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
1cfd0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 sed()] since the
1cfe0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
1cff0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 .** was last res
1d000 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 et. ^The values
1d010 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
1d020 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1d030 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c d()] and.** [sql
1d040 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
1d050 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 water()] include
1d060 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a any overhead.**
1d070 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 added by SQLite
1d080 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e in its implemen
1d090 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 tation of [sqlit
1d0a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a e3_malloc()],.**
1d0b0 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 but not overhea
1d0c0 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 d added by the a
1d0d0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 ny underlying sy
1d0e0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 stem library.**
1d0f0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 routines that [s
1d100 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1d110 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a may call..**.**
1d120 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 ^The memory hig
1d130 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 h-water mark is
1d140 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 reset to the cur
1d150 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a rent value of.**
1d160 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1d170 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 _used()] if and
1d180 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 only if the para
1d190 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c meter to.** [sql
1d1a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
1d1b0 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 water()] is true
1d1c0 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 . ^The value re
1d1d0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 turned.** by [sq
1d1e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1d1f0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 hwater(1)] is th
1d200 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
1d210 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 k.** prior to th
1d220 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 e reset..*/.sqli
1d230 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
1d240 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 3_memory_used(vo
1d250 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 id);.sqlite3_int
1d260 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
1d270 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 y_highwater(int
1d280 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a resetFlag);../*.
1d290 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 ** CAPI3REF: Pse
1d2a0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 udo-Random Numbe
1d2b0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a r Generator.**.*
1d2c0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e * SQLite contain
1d2d0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 s a high-quality
1d2e0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e pseudo-random n
1d2f0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 umber generator
1d300 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a (PRNG) used to.*
1d310 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 * select random
1d320 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d [ROWID | ROWIDs]
1d330 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
1d340 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f new records into
1d350 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a a table that.**
1d360 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 already uses th
1d370 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 e largest possib
1d380 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 le [ROWID]. The
1d390 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 PRNG is also us
1d3a0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 ed for.** the bu
1d3b0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 ild-in random()
1d3c0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 and randomblob()
1d3d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 SQL functions.
1d3e0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
1d3f0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 allows.** applic
1d400 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 ations to access
1d410 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 the same PRNG f
1d420 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 or other purpose
1d430 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c s..**.** ^A call
1d440 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
1d450 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 stores N bytes
1d460 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e of randomness in
1d470 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 to buffer P..**
1d480 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 ^If N is less th
1d490 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63 an one, then P c
1d4a0 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 an be a NULL poi
1d4b0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 nter..**.** ^If
1d4c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 this routine has
1d4d0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f not been previo
1d4e0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 usly called or i
1d4f0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a f the previous.*
1d500 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 * call had N les
1d510 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e s than one, then
1d520 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 the PRNG is see
1d530 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d ded using random
1d540 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 ness.** obtained
1d550 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f from the xRando
1d560 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 mness method of
1d570 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
1d580 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
1d590 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 ..** ^If the pre
1d5a0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
1d5b0 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 is routine had a
1d5c0 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 n N of 1 or more
1d5d0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65 then.** the pse
1d5e0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
1d5f0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
1d600 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
1d610 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
1d620 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1d630 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
1d640 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f ** method..*/.vo
1d650 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f id sqlite3_rando
1d660 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
1d670 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
1d680 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
1d690 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
1d6a0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a on Callbacks.**.
1d6b0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
1d6c0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 registers an au
1d6d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1d6e0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 k with a particu
1d6f0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
1d700 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 connection], su
1d710 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 pplied in the fi
1d720 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
1d730 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
1d740 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1d750 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
1d760 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
1d770 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
1d780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1d790 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
1d7a0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
1d7b0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
1d7c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1d7d0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
1d7e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1d7f0 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a ]. ^At various.
1d800 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
1d810 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
1d820 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
1d830 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
1d840 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
1d850 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
1d860 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
1d870 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
1d880 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
1d890 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
1d8a0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e are allowed. ^
1d8b0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
1d8c0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
1d8d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
1d8e0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
1d8f0 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
1d900 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
1d910 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
1d920 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
1d930 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
1d940 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
1d950 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
1d960 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
1d970 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
1d980 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
1d990 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
1d9a0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
1d9b0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 h an error. ^If
1d9c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1d9d0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1d9e0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 .** any value ot
1d9f0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
1da00 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
1da10 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
1da20 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 E_DENY].** then
1da30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
1da40 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
1da50 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
1da60 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 at triggered.**
1da70 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 the authorizer w
1da80 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
1da90 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
1daa0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
1dab0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1dac0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 [SQLITE_OK], tha
1dad0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 t means the oper
1dae0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 ation.** request
1daf0 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e ed is ok. ^When
1db00 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1db10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 turns [SQLITE_DE
1db20 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c NY], the.** [sql
1db30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1db40 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
1db50 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
1db60 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 ered the.** auth
1db70 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
1db80 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
1db90 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e essage explainin
1dba0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 g that.** access
1dbb0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a is denied. .**.
1dbc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
1dbd0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
1dbe0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1dbf0 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
1dc00 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
1dc10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
1dc20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1dc30 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 izer() interface
1dc40 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
1dc50 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
1dc60 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
1dc70 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
1dc80 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
1dc90 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
1dca0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
1dcb0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
1dcc0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e be authorized. ^
1dcd0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
1dce0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
1dcf0 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
1dd00 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
1dd10 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
1dd20 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
1dd30 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
1dd40 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
1dd50 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
1dd60 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 orized..**.** ^I
1dd70 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
1dd80 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
1dd90 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
1dda0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
1ddb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
1ddc0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
1ddd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1dde0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
1ddf0 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
1de00 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
1de10 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
1de20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
1de30 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
1de40 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
1de50 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
1de60 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
1de70 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
1de80 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
1de90 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
1dea0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
1deb0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
1dec0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
1ded0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
1dee0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 le..** ^If the a
1def0 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
1df00 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
1df10 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
1df20 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
1df30 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
1df40 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
1df50 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
1df60 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
1df70 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
1df80 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
1df90 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
1dfa0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
1dfb0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
1dfc0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
1dfd0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
1dfe0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
1dff0 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
1e000 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
1e010 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
1e020 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
1e030 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1e040 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
1e050 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
1e060 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
1e070 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
1e080 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
1e090 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
1e0a0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
1e0b0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
1e0c0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
1e0d0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
1e0e0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
1e0f0 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
1e100 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
1e110 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
1e120 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
1e130 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
1e140 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
1e150 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
1e160 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
1e170 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
1e180 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
1e190 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
1e1a0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
1e1b0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
1e1c0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
1e1d0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
1e1e0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
1e1f0 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
1e200 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
1e210 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
1e220 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
1e230 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
1e240 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
1e250 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
1e260 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
1e270 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
1e280 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
1e290 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
1e2a0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
1e2b0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
1e2c0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
1e2d0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
1e2e0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
1e2f0 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
1e300 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
1e310 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
1e320 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
1e330 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
1e340 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c zer..**.** ^(Onl
1e350 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
1e360 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
1e370 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
1e380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1e390 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
1e3a0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
1e3b0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1e3c0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
1e3d0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
1e3e0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 .)^ ^Disable th
1e3f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
1e400 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
1e410 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
1e420 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
1e430 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
1e440 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
1e450 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1e460 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
1e470 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
1e480 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
1e490 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1e4a0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1e4b0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
1e4c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
1e4d0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
1e4e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
1e4f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
1e500 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
1e510 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
1e520 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
1e530 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
1e540 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
1e550 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
1e560 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 ** ^When [sqlite
1e570 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1e580 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 is used to prepa
1e590 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 re a statement,
1e5a0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
1e5b0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 might be re-pre
1e5c0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 pared during [sq
1e5d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 lite3_step()] du
1e5e0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d e to a .** schem
1e5f0 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 a change. Hence
1e600 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
1e610 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 n should ensure
1e620 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 that the.** corr
1e630 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 ect authorizer c
1e640 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 allback remains
1e650 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 in place during
1e660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
1e670 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 p()]..**.** ^Not
1e680 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
1e690 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1e6a0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
1e6b0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
1e6c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
1e6d0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
1e6e0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
1e6f0 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
1e700 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
1e710 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
1e720 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1e730 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 , unless.** as s
1e740 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 tated in the pre
1e750 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c vious paragraph,
1e760 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
1e770 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 invokes.** sqlit
1e780 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
1e790 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 to reprepare a s
1e7a0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 tatement after a
1e7b0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a schema change..
1e7c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
1e7d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
1e7e0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
1e7f0 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
1e800 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
1e810 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1e820 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1e830 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
1e840 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
1e850 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
1e860 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
1e870 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
1e880 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1e890 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1e8a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1e8b0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
1e8c0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
1e8d0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
1e8e0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
1e8f0 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
1e900 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
1e910 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
1e920 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
1e930 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
1e940 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1e950 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1e960 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
1e970 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
1e980 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
1e990 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
1e9a0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 Note that SQLITE
1e9b0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 _IGNORE is also
1e9c0 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 used as a [SQLIT
1e9d0 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 E_ROLLBACK | ret
1e9e0 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f urn code].** fro
1e9f0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
1ea00 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
1ea10 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f )] interface..*/
1ea20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ea30 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 DENY 1 /* Ab
1ea40 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 ort the SQL stat
1ea50 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 ement with an er
1ea60 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
1ea70 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 QLITE_IGNORE 2
1ea80 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 /* Don't allow
1ea90 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 access, but don'
1eaa0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 t generate an er
1eab0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ror */../*.** CA
1eac0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1ead0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a er Action Codes.
1eae0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
1eaf0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1eb00 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 r()] interface r
1eb10 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
1eb20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
1eb30 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 that is invoked
1eb40 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 to authorize cer
1eb50 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 tain SQL stateme
1eb60 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 nt actions. The
1eb70 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
1eb80 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
1eb90 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
1eba0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 er code that spe
1ebb0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 cifies.** what a
1ebc0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 ction is being a
1ebd0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 uthorized. Thes
1ebe0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 e are the intege
1ebf0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 r action codes t
1ec00 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f hat.** the autho
1ec10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
1ec20 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a ay be passed..**
1ec30 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e .** These action
1ec40 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 code values sig
1ec50 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f nify what kind o
1ec60 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 f operation is t
1ec70 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a o be.** authoriz
1ec80 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 ed. The 3rd and
1ec90 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 4th parameters
1eca0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 to the authoriza
1ecb0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
1ecc0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 function will b
1ecd0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 e parameters or
1ece0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f NULL depending o
1ecf0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 n which of these
1ed00 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 .** codes is use
1ed10 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1ed20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 parameter. ^(Th
1ed30 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
1ed40 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 to the.** author
1ed50 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1ed60 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1ed70 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e database ("main
1ed80 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 ", "temp",.** et
1ed90 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
1eda0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 e.)^ ^The 6th p
1edb0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1edc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1edd0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
1ede0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
1edf0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
1ee00 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
1ee10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
1ee20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
1ee30 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
1ee40 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
1ee50 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
1ee60 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
1ee70 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a SQL code..*/./**
1ee80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1ee90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1eea0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a ********* 3rd **
1eeb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a ********** 4th *
1eec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 **********/.#def
1eed0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1eee0 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 E_INDEX
1eef0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 1 /* Index Na
1ef00 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1ef10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1ef20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1ef30 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
1ef40 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 2 /* Table Nam
1ef50 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1ef60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ef70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1ef80 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 TEMP_INDEX 3
1ef90 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1efa0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1efb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1efc0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1efd0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 EMP_TABLE 4
1efe0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1eff0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1f000 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1f010 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1f020 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 MP_TRIGGER 5
1f030 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1f040 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1f050 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1f060 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1f070 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 P_VIEW 6
1f080 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
1f090 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1f0a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f0b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 LITE_CREATE_TRIG
1f0c0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f GER 7 /
1f0d0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
1f0e0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1f0f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f100 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 ITE_CREATE_VIEW
1f110 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 8 /*
1f120 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
1f130 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1f140 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f150 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 TE_DELETE
1f160 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 9 /*
1f170 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1f180 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f1a0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 E_DROP_INDEX
1f1b0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 10 /* I
1f1c0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
1f1d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1f1e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f1f0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 _DROP_TABLE
1f200 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 11 /* Ta
1f210 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1f220 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1f230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f240 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 DROP_TEMP_INDEX
1f250 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 12 /* Ind
1f260 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1f270 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1f280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1f290 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ROP_TEMP_TABLE
1f2a0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 13 /* Tabl
1f2b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1f2c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1f2d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1f2e0 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 OP_TEMP_TRIGGER
1f2f0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 14 /* Trigg
1f300 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
1f310 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1f320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1f330 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 P_TEMP_VIEW
1f340 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 15 /* View N
1f350 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
1f360 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1f370 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1f380 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
1f390 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 16 /* Trigger
1f3a0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1f3b0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1f3c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1f3d0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 VIEW
1f3e0 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 17 /* View Nam
1f3f0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1f400 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1f410 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 ne SQLITE_INSERT
1f420 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1f430 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
1f440 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1f450 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1f460 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 e SQLITE_PRAGMA
1f470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
1f480 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d /* Pragma Nam
1f490 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 e 1st arg or
1f4a0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 NULL */.#define
1f4b0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 SQLITE_READ
1f4c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20
1f4d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1f4e0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 Column Name
1f4f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1f500 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 SQLITE_SELECT
1f510 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 21
1f520 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
1f530 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1f540 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1f550 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f QLITE_TRANSACTIO
1f560 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 N 22
1f570 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
1f580 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1f590 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f5a0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 LITE_UPDATE
1f5b0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 23 /
1f5c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1f5d0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
1f5e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f5f0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 ITE_ATTACH
1f600 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 24 /*
1f610 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 Filename
1f620 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1f630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f640 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 TE_DETACH
1f650 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 25 /*
1f660 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
1f670 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f690 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 E_ALTER_TABLE
1f6a0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 26 /* D
1f6b0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 atabase Name T
1f6c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1f6d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f6e0 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 _REINDEX
1f6f0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 27 /* In
1f700 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 dex Name NU
1f710 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1f720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f730 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 ANALYZE
1f740 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 28 /* Tab
1f750 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1f760 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1f770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1f780 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 REATE_VTABLE
1f790 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 29 /* Tabl
1f7a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
1f7b0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
1f7c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1f7d0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 OP_VTABLE
1f7e0 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 30 /* Table
1f7f0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
1f800 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
1f810 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e efine SQLITE_FUN
1f820 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 CTION
1f830 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 31 /* NULL
1f840 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 Functi
1f850 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 on Name */.#de
1f860 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 fine SQLITE_SAVE
1f870 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 POINT
1f880 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 32 /* Operati
1f890 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 on Savepoi
1f8a0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 nt Name */.#def
1f8b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 ine SQLITE_COPY
1f8c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1f8d0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 0 /* No longe
1f8e0 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e r used */.#defin
1f8f0 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 e SQLITE_RECURSI
1f900 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 VE 33
1f910 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
1f920 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1f930 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 */../*.**
1f940 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e CAPI3REF: Tracin
1f950 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 g And Profiling
1f960 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
1f970 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
1f980 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b egister callback
1f990 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
1f9a0 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a can be used for.
1f9b0 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 ** tracing and p
1f9c0 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 rofiling the exe
1f9d0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 cution of SQL st
1f9e0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
1f9f0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 ^The callback fu
1fa00 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 nction registere
1fa10 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 d by sqlite3_tra
1fa20 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ce() is invoked
1fa30 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 at.** various ti
1fa40 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 mes when an SQL
1fa50 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 statement is bei
1fa60 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 ng run by [sqlit
1fa70 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e e3_step()]..** ^
1fa80 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
1fa90 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 e() callback is
1faa0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 invoked with a U
1fab0 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f TF-8 rendering o
1fac0 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 f the.** SQL sta
1fad0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 tement text as t
1fae0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 he statement fir
1faf0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 st begins execut
1fb00 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 ing..** ^(Additi
1fb10 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 onal sqlite3_tra
1fb20 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d ce() callbacks m
1fb30 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 ight occur.** as
1fb40 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 each triggered
1fb50 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e subprogram is en
1fb60 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c tered. The call
1fb70 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 backs for trigge
1fb80 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 rs.** contain a
1fb90 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e UTF-8 SQL commen
1fba0 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 t that identifie
1fbb0 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e s the trigger.)^
1fbc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
1fbd0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 TE_TRACE_SIZE_LI
1fbe0 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d MIT] compile-tim
1fbf0 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 e option can be
1fc00 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a used to limit.**
1fc10 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b the length of [
1fc20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d bound parameter]
1fc30 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 expansion in th
1fc40 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 e output of sqli
1fc50 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a te3_trace()..**.
1fc60 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b ** ^The callback
1fc70 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
1fc80 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
1fc90 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 profile() is inv
1fca0 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 oked.** as each
1fcb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 SQL statement fi
1fcc0 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 nishes. ^The pr
1fcd0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
1fce0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
1fcf0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
1fd00 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
1fd10 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
1fd20 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
1fd30 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
1fd40 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
1fd50 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 run. ^The profi
1fd60 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 le callback.** t
1fd70 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 ime is in units
1fd80 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 of nanoseconds,
1fd90 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 however the curr
1fda0 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ent implementati
1fdb0 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 on.** is only ca
1fdc0 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 pable of millise
1fdd0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 cond resolution
1fde0 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 so the six least
1fdf0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 significant.**
1fe00 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 digits in the ti
1fe10 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 me are meaningle
1fe20 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ss. Future vers
1fe30 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a ions of SQLite.*
1fe40 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 * might provide
1fe50 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 greater resoluti
1fe60 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c on on the profil
1fe70 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 er callback. Th
1fe80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f e.** sqlite3_pro
1fe90 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 file() function
1fea0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 is considered ex
1feb0 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
1fec0 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 s.** subject to
1fed0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 change in future
1fee0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
1fef0 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ite..*/.void *sq
1ff00 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 lite3_trace(sqli
1ff10 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 te3*, void(*xTra
1ff20 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 ce)(void*,const
1ff30 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a char*), void*);.
1ff40 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e SQLITE_EXPERIMEN
1ff50 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 TAL void *sqlite
1ff60 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 3_profile(sqlite
1ff70 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 3*,. void(*xPr
1ff80 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e ofile)(void*,con
1ff90 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 st char*,sqlite3
1ffa0 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 _uint64), void*)
1ffb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1ffc0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 F: Query Progres
1ffd0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a s Callbacks.**.*
1ffe0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 * ^The sqlite3_p
1fff0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
20000 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 D,N,X,P) interfa
20010 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 ce causes the ca
20020 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
20030 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b on X to be invok
20040 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 ed periodically
20050 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e during long runn
20060 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ing calls to.**
20070 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d [sqlite3_exec()]
20080 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
20090 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
200a0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 get_table()] for
200b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
200c0 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 nection D. An e
200d0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 xample use for t
200e0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 his.** interface
200f0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 is to keep a GU
20100 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 I updated during
20110 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a a large query..
20120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d **.** ^The param
20130 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 eter P is passed
20140 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 through as the
20150 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
20160 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 o the .** callba
20170 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 ck function X.
20180 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e ^The parameter N
20190 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d is the approxim
201a0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a ate number of .*
201b0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 * [virtual machi
201c0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d ne instructions]
201d0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 that are evalua
201e0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 ted between succ
201f0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 essive.** invoca
20200 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c tions of the cal
20210 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 lback X. ^If N
20220 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 is less than one
20230 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 then the progre
20240 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 ss.** handler is
20250 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a disabled..**.**
20260 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 ^Only a single
20270 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
20280 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 may be defined
20290 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a at one time per.
202a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
202b0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e nection]; settin
202c0 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 g a new progress
202d0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 handler cancels
202e0 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e the.** old one.
202f0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d ^Setting param
20300 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 eter X to NULL d
20310 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 isables the prog
20320 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a ress handler..**
20330 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 ^The progress h
20340 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 andler is also d
20350 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 isabled by setti
20360 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 ng N to a value
20370 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a less.** than 1..
20380 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 **.** ^If the pr
20390 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 ogress callback
203a0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
203b0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 , the operation
203c0 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 is.** interrupte
203d0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 d. This feature
203e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
203f0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 implement a.** "
20400 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f Cancel" button o
20410 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 n a GUI progress
20420 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a dialog box..**.
20430 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 ** The progress
20440 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
20450 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 must not do any
20460 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 thing that will
20470 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 modify.** the da
20480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20490 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 n that invoked t
204a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
204b0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ler..** Note tha
204c0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 t [sqlite3_prepa
204d0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
204e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f lite3_step()] bo
204f0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a th modify their.
20500 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
20510 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 ections for the
20520 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 meaning of "modi
20530 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 fy" in this para
20540 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 graph..**.*/.voi
20550 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 d sqlite3_progre
20560 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 ss_handler(sqlit
20570 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 e3*, int, int(*)
20580 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
20590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
205a0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 : Opening A New
205b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
205c0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 ion.**.** ^These
205d0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
205e0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
205f0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 e file as specif
20600 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 ied by the .** f
20610 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
20620 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 . ^The filename
20630 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 argument is inte
20640 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 rpreted as UTF-8
20650 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
20660 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
20670 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 e3_open_v2() and
20680 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 as UTF-16 in th
20690 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a e native byte.**
206a0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
206b0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 e3_open16(). ^(A
206c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
206d0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 ction] handle is
206e0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 usually.** retu
206f0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 rned in *ppDb, e
20700 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 ven if an error
20710 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c occurs. The onl
20720 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 y exception is t
20730 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 hat.** if SQLite
20740 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
20750 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
20760 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 hold the [sqlit
20770 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 e3] object,.** a
20780 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 NULL will be wr
20790 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 itten into *ppDb
207a0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f instead of a po
207b0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
207c0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 lite3].** object
207d0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 .)^ ^(If the dat
207e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
207f0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 (and/or created)
20800 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 successfully, t
20810 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f hen.** [SQLITE_O
20820 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 K] is returned.
20830 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
20840 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
20850 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a turned.)^ ^The.*
20860 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
20870 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 g()] or [sqlite3
20880 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 _errmsg16()] rou
20890 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 tines can be use
208a0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 d to obtain.** a
208b0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 n English langua
208c0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f ge description o
208d0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c f the error foll
208e0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 owing a failure
208f0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
20900 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
20910 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
20920 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
20930 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 oding for the da
20940 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 tabase will be U
20950 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 TF-8 if.** sqlit
20960 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
20970 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
20980 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 s called and.**
20990 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 UTF-16 in the na
209a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
209b0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 if sqlite3_open1
209c0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 6() is used..**.
209d0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
209e0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
209f0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
20a00 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
20a10 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
20a20 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
20a30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
20a40 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
20a50 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
20a60 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
20a70 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
20a80 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
20a90 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
20aa0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
20ab0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
20ac0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
20ad0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
20ae0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
20af0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
20b00 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
20b10 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
20b20 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
20b30 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
20b40 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 onnection. ^(Th
20b50 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
20b60 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
20b70 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 open_v2() can ta
20b80 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 ke one of.** the
20b90 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 following three
20ba0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 values, optiona
20bb0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
20bc0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
20bd0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c E_OPEN_NOMUTEX],
20be0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
20bf0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 LLMUTEX], [SQLIT
20c00 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
20c10 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f HE],.** [SQLITE_
20c20 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
20c30 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 E], and/or [SQLI
20c40 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
20c50 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e gs:)^.**.** <dl>
20c60 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
20c70 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
20c80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
20c90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
20ca0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
20cb0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
20cc0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
20cd0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
20ce0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
20cf0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
20d00 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
20d10 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
20d20 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
20d30 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
20d40 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
20d50 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
20d60 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
20d70 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
20d80 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
20d90 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
20da0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
20db0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
20dc0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
20dd0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
20de0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
20df0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
20e00 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
20e10 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
20e20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
20e30 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
20e40 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
20e50 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
20e60 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
20e70 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
20e80 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
20e90 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 created if.** it
20ea0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
20eb0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
20ec0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
20ed0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
20ee0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
20ef0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
20f00 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
20f10 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a d>)^.** </dl>.**
20f20 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
20f30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
20f40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
20f50 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
20f60 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
20f70 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 shown above opti
20f80 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
20f90 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 with other.** [S
20fa0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
20fb0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 NLY | SQLITE_OPE
20fc0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 N_* bits].** the
20fd0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
20fe0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
20ff0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
21000 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
21010 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
21020 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
21030 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
21040 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
21050 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
21060 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
21070 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
21080 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
21090 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
210a0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
210b0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
210c0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
210d0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
210e0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
210f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
21100 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
21110 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
21120 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
21130 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
21140 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
21150 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
21160 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
21170 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
21180 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
21190 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
211a0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
211b0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
211c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
211d0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
211e0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
211f0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
21200 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
21210 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
21220 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
21230 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
21240 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
21250 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
21260 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
21270 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
21280 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
21290 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
212a0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
212b0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
212c0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
212d0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
212e0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
212f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
21300 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
21310 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
21320 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
21330 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
21340 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
21350 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
21360 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
21370 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
21380 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
21390 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 should use. ^I
213a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
213b0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
213c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
213d0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
213e0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
213f0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
21400 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
21410 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c e is ":memory:",
21420 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
21430 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 temporary in-me
21440 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mory database.**
21450 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 is created for
21460 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 the connection.
21470 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 ^This in-memory
21480 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 database will v
21490 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 anish when.** th
214a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
214b0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
214c0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
214d0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
214e0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 t.** make use of
214f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 additional spec
21500 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 ial filenames th
21510 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 at begin with th
21520 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e e ":" character.
21530 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d .** It is recomm
21540 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 ended that when
21550 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e a database filen
21560 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 ame actually doe
21570 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 s begin with.**
21580 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 a ":" character
21590 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 you should prefi
215a0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 x the filename w
215b0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 ith a pathname s
215c0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 uch as.** "./" t
215d0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 o avoid ambiguit
215e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 y..**.** ^If the
215f0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
21600 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
21610 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
21620 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
21630 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
21640 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 be created. ^T
21650 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 his private data
21660 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 base will be.**
21670 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
21680 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 leted as soon as
21690 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
216a0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
216b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 ed..**.** [[URI
216c0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c filenames in sql
216d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 ite3_open()]] <h
216e0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 3>URI Filenames<
216f0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b /h3>.**.** ^If [
21700 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e URI filename] in
21710 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
21720 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 enabled, and the
21730 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
21740 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 nt.** begins wit
21750 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 h "file:", then
21760 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
21770 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
21780 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 URI. ^URI.** fi
21790 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
217a0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
217b0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
217c0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
217d0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 s.** set in the
217e0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
217f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
21800 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 v2(), or if it h
21810 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c as.** been enabl
21820 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e ed globally usin
21830 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
21840 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e NFIG_URI] option
21850 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 with the.** [sq
21860 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
21870 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 method or by the
21880 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
21890 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
218a0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 ption..** As of
218b0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
218c0 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 .7.7, URI filena
218d0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f me interpretatio
218e0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a n is turned off.
218f0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 ** by default, b
21900 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ut future releas
21910 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 es of SQLite mig
21920 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 ht enable URI fi
21930 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 lename.** interp
21940 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 retation by defa
21950 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 ult. See "[URI
21960 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 filenames]" for
21970 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
21980 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
21990 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 URI filenames a
219a0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 re parsed accord
219b0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e ing to RFC 3986.
219c0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e ^If the URI con
219d0 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 tains an.** auth
219e0 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d ority, then it m
219f0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e ust be either an
21a00 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
21a10 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 the string .**
21a20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 "localhost". ^If
21a30 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 the authority i
21a40 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 s not an empty s
21a50 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 tring or "localh
21a60 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 ost", an .** err
21a70 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 or is returned t
21a80 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 o the caller. ^T
21a90 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 he fragment comp
21aa0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 onent of a URI,
21ab0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 if .** present,
21ac0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
21ad0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
21ae0 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e he path componen
21af0 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 t of the URI as
21b00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
21b10 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 disk file.** whi
21b20 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ch contains the
21b30 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 database. ^If th
21b40 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 e path begins wi
21b50 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 th a '/' charact
21b60 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 er, .** then it
21b70 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
21b80 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 s an absolute pa
21b90 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 th. ^If the path
21ba0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 does not begin
21bb0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 .** with a '/' (
21bc0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 meaning that the
21bd0 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 authority secti
21be0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 on is omitted fr
21bf0 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 om the URI).** t
21c00 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 hen the path is
21c10 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
21c20 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 relative path.
21c30 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c .** ^On windows,
21c40 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f the first compo
21c50 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c nent of an absol
21c60 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 ute path .** is
21c70 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 a drive specific
21c80 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 ation (e.g. "C:"
21c90 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 )..**.** [[core
21ca0 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 URI query parame
21cb0 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 ters]].** The qu
21cc0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
21cd0 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 a URI may conta
21ce0 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 in parameters th
21cf0 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 at are interpret
21d00 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 ed.** either by
21d10 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f SQLite itself, o
21d20 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 r by a [VFS | cu
21d30 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 stom VFS impleme
21d40 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c ntation]..** SQL
21d50 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 ite interprets t
21d60 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 he following thr
21d70 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 ee query paramet
21d80 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ers:.**.** <ul>.
21d90 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 ** <li> <b>vfs
21da0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 </b>: ^The "vfs"
21db0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
21dc0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 e used to specif
21dd0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a y the name of.**
21de0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 a VFS objec
21df0 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 t that provides
21e00 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 the operating sy
21e10 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 stem interface t
21e20 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 hat should.**
21e30 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 be used to acc
21e40 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
21e50 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e file on disk. ^
21e60 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 If this option i
21e70 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 s set to.**
21e80 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 an empty string
21e90 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 the default VFS
21ea0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 object is used.
21eb0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 ^Specifying an u
21ec0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 nknown.** VF
21ed0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e S is an error. ^
21ee0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
21ef0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 v2() is used and
21f00 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 the vfs option
21f10 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e is.** presen
21f20 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 t, then the VFS
21f30 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
21f40 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 option takes pr
21f50 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a ecedence over.**
21f60 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 the value p
21f70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 assed as the fou
21f80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
21f90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
21fa0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e ()..**.** <li>
21fb0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 <b>mode</b>: ^(
21fc0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 The mode paramet
21fd0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f er may be set to
21fe0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 either "ro", "r
21ff0 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 w",.** "rwc"
22000 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 , or "memory". A
22010 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 ttempting to set
22020 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 it to any other
22030 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 value is.**
22040 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a an error)^. .**
22050 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 ^If "ro" is
22060 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e specified, then
22070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
22080 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
22090 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 -only .** ac
220a0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 cess, just as if
220b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
220c0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 N_READONLY] flag
220d0 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e had been set in
220e0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 the .** thi
220f0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
22100 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
22110 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f . ^If the mode o
22120 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 ption is set to
22130 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 .** "rw", th
22140 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
22150 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
22160 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f ad-write (but no
22170 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 t create) .**
22180 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 access, as if
22190 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
221a0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 WRITE (but not S
221b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
221c0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 E) had .** b
221d0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 een set. ^Value
221e0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c "rwc" is equival
221f0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 ent to setting b
22200 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 oth .** SQLI
22210 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
22220 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 E and SQLITE_OPE
22230 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 N_CREATE. ^If t
22240 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 he mode option i
22250 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 s.** set to
22260 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 "memory" then a
22270 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 pure [in-memory
22280 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e database] that n
22290 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 ever reads.**
222a0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d or writes from
222b0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e disk is used. ^
222c0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 It is an error t
222d0 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 o specify a valu
222e0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 e for.** the
222f0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 mode parameter
22300 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 that is less res
22310 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 trictive than th
22320 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a at specified by.
22330 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 ** the flags
22340 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 passed in the t
22350 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
22360 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
22370 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 2()..**.** <li
22380 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 > <b>cache</b>:
22390 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d ^The cache param
223a0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 eter may be set
223b0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 to either "share
223c0 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 d" or.** "pr
223d0 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 ivate". ^Setting
223e0 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 it to "shared"
223f0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f is equivalent to
22400 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 setting the.**
22410 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
22420 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 SHAREDCACHE bit
22430 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 in the flags arg
22440 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a ument passed to.
22450 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f ** sqlite3_o
22460 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 pen_v2(). ^Setti
22470 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 ng the cache par
22480 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 ameter to "priva
22490 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 te" is .** e
224a0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 quivalent to set
224b0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f ting the SQLITE_
224c0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
224d0 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 E bit..** ^I
224e0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 f sqlite3_open_v
224f0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 2() is used and
22500 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 the "cache" para
22510 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 meter is present
22520 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 in.** a URI
22530 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 filename, its v
22540 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 alue overrides a
22550 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 ny behavior requ
22560 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 ested by setting
22570 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f .** SQLITE_O
22580 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
22590 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or SQLITE_OPEN_
225a0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 SHAREDCACHE flag
225b0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 ..**.** <li> <b
225c0 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 >psow</b>: ^The
225d0 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 6d psow parameter m
225e0 61 79 20 62 65 20 22 74 72 75 65 22 20 28 6f 72 ay be "true" (or
225f0 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22 20 6f "on" or "yes" o
22600 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20 6f 72 r.** "1") or
22610 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22 6f 66 "false" (or "of
22620 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30 f" or "no" or "0
22630 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ") to indicate t
22640 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b hat the.** [
22650 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 powersafe overwr
22660 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f ite] property do
22670 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 es or does not a
22680 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 pply to the.**
22690 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 storage media
226a0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 on which the da
226b0 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 tabase file resi
226c0 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f 77 20 des. ^The psow
226d0 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 query.** par
226e0 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b ameter only work
226f0 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c 74 2d s for the built-
22700 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69 6e 64 in unix and Wind
22710 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a ows VFSes..**.**
22720 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b <li> <b>nolock
22730 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 </b>: ^The noloc
22740 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 k parameter is a
22750 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 boolean query p
22760 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 arameter.**
22770 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 which if set dis
22780 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 ables file locki
22790 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a ng in rollback j
227a0 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 ournal modes. T
227b0 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 his.** is us
227c0 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 eful for accessi
227d0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e ng a database on
227e0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 a filesystem th
227f0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 at does not.**
22800 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 support locki
22810 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 ng. Caution: D
22820 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 atabase corrupti
22830 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 on might result
22840 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 if two.** or
22850 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 more processes
22860 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d write to the sam
22870 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 e database and a
22880 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a ny one of those.
22890 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 ** processes
228a0 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a uses nolock=1..
228b0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 **.** <li> <b>i
228c0 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 mmutable</b>: ^T
228d0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 he immutable par
228e0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c ameter is a bool
228f0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 ean query.**
22900 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 parameter that
22910 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 indicates that t
22920 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
22930 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a is stored on.**
22940 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d read-only m
22950 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d edia. ^When imm
22960 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 utable is set, S
22970 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
22980 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 at the.** da
22990 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e tabase file cann
229a0 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 ot be changed, e
229b0 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 ven by a process
229c0 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 with higher.**
229d0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 privilege, a
229e0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 nd so the databa
229f0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 se is opened rea
22a00 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c d-only and all l
22a10 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e ocking.** an
22a20 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 d change detecti
22a30 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 on is disabled.
22a40 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e Caution: Settin
22a50 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a g the immutable.
22a60 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 ** property
22a70 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 on a database fi
22a80 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 le that does in
22a90 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 fact change can
22aa0 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e result.** in
22ab0 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 incorrect query
22ac0 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 results and/or
22ad0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d [SQLITE_CORRUPT]
22ae0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 errors..**
22af0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 See also: [SQLIT
22b00 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
22b10 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a E]..** .**
22b20 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 </ul>.**.** ^Sp
22b30 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e ecifying an unkn
22b40 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e own parameter in
22b50 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f the query compo
22b60 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 nent of a URI is
22b70 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 not an.** error
22b80 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
22b90 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
22ba0 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 ht understand ad
22bb0 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a ditional query.*
22bc0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 * parameters. S
22bd0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d ee "[query param
22be0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 eters with speci
22bf0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 al meaning to SQ
22c00 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 Lite]" for.** ad
22c10 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
22c20 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 tion..**.** [[UR
22c30 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 I filename examp
22c40 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 les]] <h3>URI fi
22c50 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c lename examples<
22c60 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c /h3>.**.** <tabl
22c70 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 e border="1" ali
22c80 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 gn=center cellpa
22c90 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e dding=5>.** <tr>
22ca0 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d <th> URI filenam
22cb0 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a es <th> Results.
22cc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
22cd0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a :data.db <td> .*
22ce0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
22cf0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 the file "data.d
22d00 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
22d10 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 t directory..**
22d20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
22d30 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
22d40 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <br>.**
22d50 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 file:///home/fr
22d60 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 ed/data.db <br>
22d70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
22d80 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f e://localhost/ho
22d90 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
22da0 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 <br> <td> .**
22db0 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
22dc0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f database file "/
22dd0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
22de0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 b"..** <tr><td>
22df0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f file://darkstar/
22e00 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
22e10 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
22e20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 An error. "d
22e30 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 arkstar" is not
22e40 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 a recognized aut
22e50 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c hority..** <tr><
22e60 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d td style="white-
22e70 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a space:nowrap"> .
22e80 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
22e90 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 :///C:/Documents
22ea0 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 %20and%20Setting
22eb0 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 s/fred/Desktop/d
22ec0 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 ata.db.** <t
22ed0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a d> Windows only:
22ee0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
22ef0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 data.db" on fred
22f00 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 's desktop on dr
22f10 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ive.**
22f20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 C:. Note that th
22f30 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 e %20 escaping i
22f40 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 n this example i
22f50 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a s not strictly .
22f60 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 ** nece
22f70 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 ssary - space ch
22f80 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 aracters can be
22f90 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a used literally.*
22fa0 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 * in UR
22fb0 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 I filenames..**
22fc0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
22fd0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 ta.db?mode=ro&ca
22fe0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e che=private <td>
22ff0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
23000 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 en file "data.db
23010 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 " in the current
23020 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 directory for r
23030 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e ead-only access.
23040 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 .** Reg
23050 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
23060 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 er or not shared
23070 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 -cache mode is e
23080 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 nabled by.**
23090 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 default, u
230a0 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 se a private cac
230b0 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 he..** <tr><td>
230c0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f file:/home/fred/
230d0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 data.db?vfs=unix
230e0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a -dotfile <td>.**
230f0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
23100 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
23110 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 data.db". Use th
23120 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 e special VFS "u
23130 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 nix-dotfile".**
23140 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 that us
23150 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 es dot-files in
23160 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 place of posix a
23170 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e dvisory locking.
23180 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
23190 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 e:data.db?mode=r
231a0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a eadonly <td> .**
231b0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
231c0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 or. "readonly" i
231d0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 s not a valid op
231e0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f tion for the "mo
231f0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a de" parameter..*
23200 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a * </table>.**.**
23210 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 ^URI hexadecima
23220 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
23230 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 es (%HH) are sup
23240 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 ported within th
23250 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 e path and.** qu
23260 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
23270 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 f a URI. A hexad
23280 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
23290 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 quence consists
232a0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 of a.** percent
232b0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c sign - "%" - fol
232c0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 lowed by exactly
232d0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c two hexadecimal
232e0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 digits .** spec
232f0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 ifying an octet
23300 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 value. ^Before t
23310 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 he path or query
23320 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
23330 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
23340 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
23350 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 , they are encod
23360 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 ed using UTF-8 a
23370 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 nd all .** hexad
23380 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
23390 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 quences replaced
233a0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 by a single byt
233b0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
233c0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e .** correspondin
233d0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 g octet. If this
233e0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 process generat
233f0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 es an invalid UT
23400 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a F-8 encoding,.**
23410 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
23420 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
23430 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
23440 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
23450 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
23460 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
23470 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
23480 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
23490 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
234a0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
234b0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
234c0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
234d0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
234e0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
234f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
23500 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
23510 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
23520 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
23530 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
23540 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
23550 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
23560 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
23570 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e v2()..**.** <b>N
23580 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 ote to Windows R
23590 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 untime users:</b
235a0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 > The temporary
235b0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 directory must
235c0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 be set.** prior
235d0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 to calling sqlit
235e0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
235f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
23600 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 Otherwise, vari
23610 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 ous.** features
23620 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 that require the
23630 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 use of temporar
23640 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c y files may fail
23650 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
23660 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f : [sqlite3_temp_
23670 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e directory].*/.in
23680 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
23690 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
236a0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
236b0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
236c0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
236d0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
236e0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
236f0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
23700 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
23710 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
23720 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
23730 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
23740 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
23750 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
23760 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
23770 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
23780 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
23790 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
237a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
237b0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
237c0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
237d0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
237e0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
237f0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
23800 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
23810 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
23820 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
23830 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
23840 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
23850 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
23860 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
23870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23880 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 EF: Obtain Value
23890 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 s For URI Parame
238a0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ters.**.** These
238b0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 are utility rou
238c0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f tines, useful to
238d0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
238e0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b ions, that check
238f0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 .** to see if a
23900 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
23910 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e s a URI that con
23920 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 tained a specifi
23930 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 c query .** para
23940 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f meter, and if so
23950 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c obtains the val
23960 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 ue of that query
23970 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
23980 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 * If F is the da
23990 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
239a0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 pointer passed i
239b0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 nto the xOpen()
239c0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 method of .** a
239d0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
239e0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 on when the flag
239f0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 s parameter to x
23a00 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f Open() has one o
23a10 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 r .** more of th
23a20 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
23a30 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f RI] or [SQLITE_O
23a40 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 PEN_MAIN_DB] bit
23a50 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 s set and.** P i
23a60 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
23a70 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
23a80 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 r, then.** sqlit
23a90 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
23aa0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 (F,P) returns th
23ab0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 e value of the P
23ac0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 .** parameter if
23ad0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 it exists or a
23ae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
23af0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 P does not appea
23b00 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 r as a .** query
23b10 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e parameter on F.
23b20 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 If P is a quer
23b30 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 y parameter of F
23b40 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 .** has no expli
23b50 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 cit value, then
23b60 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
23b70 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
23b80 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ns.** a pointer
23b90 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
23ba0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ng..**.** The sq
23bb0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
23bc0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
23bd0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 assumes that P
23be0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 is a boolean.**
23bf0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
23c00 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f turns true (1) o
23c10 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f r false (0) acco
23c20 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c rding to the val
23c30 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 ue.** of P. The
23c40 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
23c50 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
23c60 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ine returns true
23c70 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 (1) if the.** v
23c80 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 alue of query pa
23c90 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
23ca0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 of "yes", "true
23cb0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e ", or "on" in an
23cc0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 y.** case or if
23cd0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
23ce0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f with a non-zero
23cf0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a number. The .*
23d00 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
23d10 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
23d20 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 tines returns fa
23d30 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 lse (0) if the v
23d40 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 alue of.** query
23d50 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
23d60 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 one of "no", "fa
23d70 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 lse", or "off" i
23d80 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a n any case or.**
23d90 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
23da0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 gins with a nume
23db0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 ric zero. If P
23dc0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a is not a query.*
23dd0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 * parameter on F
23de0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
23df0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f of P is does no
23e00 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 t match any of t
23e10 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 he.** above, the
23e20 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f n sqlite3_uri_bo
23e30 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
23e40 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a urns (B!=0)..**.
23e50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
23e60 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 ri_int64(F,P,D)
23e70 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 routine converts
23e80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
23e90 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 into a.** 64-bit
23ea0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
23eb0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 and returns that
23ec0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 integer, or D i
23ed0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 f P does not.**
23ee0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 exist. If the v
23ef0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d alue of P is som
23f00 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
23f10 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 n an integer, th
23f20 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 en.** zero is re
23f30 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 turned..** .** I
23f40 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f F is a NULL po
23f50 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 inter, then sqli
23f60 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
23f70 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e r(F,P) returns N
23f80 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 ULL and.** sqlit
23f90 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
23fa0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e ,P,B) returns B.
23fb0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 If F is not a
23fc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
23fd0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 .** is not a dat
23fe0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e abase file pathn
23ff0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ame pointer that
24000 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 SQLite passed i
24010 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a nto the xOpen.**
24020 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 VFS method, the
24030 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
24040 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 f this routine i
24050 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
24060 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 probably.** unde
24070 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 sirable..*/.cons
24080 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
24090 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f uri_parameter(co
240a0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
240b0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ame, const char
240c0 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 *zParam);.int sq
240d0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
240e0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 n(const char *zF
240f0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ile, const char
24100 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 *zParam, int bDe
24110 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f fault);.sqlite3_
24120 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 int64 sqlite3_ur
24130 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 i_int64(const ch
24140 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a ar*, const char*
24150 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
24160 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
24170 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
24180 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a And Messages.**.
24190 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
241a0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 errcode() interf
241b0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
241c0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
241d0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
241e0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
241f0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 e] for the most
24200 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 recent failed sq
24210 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
24220 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
24230 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
24240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 connection]. If
24250 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c a prior API call
24260 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 failed.** but t
24270 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
24280 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 PI call succeede
24290 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 d, the return va
242a0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 lue from.** sqli
242b0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
242c0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 undefined. ^Th
242d0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
242e0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
242f0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
24300 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
24310 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
24320 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
24330 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
24340 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
24350 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
24360 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
24370 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
24380 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
24390 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
243a0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
243b0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
243c0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
243d0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
243e0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
243f0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
24400 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 ctively..** ^(Me
24410 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
24420 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
24430 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
24440 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
24450 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
24460 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
24470 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
24480 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
24490 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
244a0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
244b0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
244c0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
244d0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
244e0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
244f0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
24500 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a ce functions.)^.
24510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
24520 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 e3_errstr() inte
24530 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
24540 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 e English-langua
24550 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 ge text.** that
24560 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 describes the [r
24570 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 esult code], as
24580 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f UTF-8..** ^(Memo
24590 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
245a0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
245b0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
245c0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 nternally.** and
245d0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 must not be fre
245e0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
245f0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 ation)^..**.** W
24600 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a hen the serializ
24610 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
24620 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 de] is in use, i
24630 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a t might be the.*
24640 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 * case that a se
24650 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 cond error occur
24660 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 s on a separate
24670 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 thread in betwee
24680 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 n.** the time of
24690 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 the first error
246a0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f and the call to
246b0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
246c0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 s..** When that
246d0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 happens, the sec
246e0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 ond error will b
246f0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 e reported since
24700 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 these.** interf
24710 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f aces always repo
24720 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 rt the most rece
24730 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 nt result. To a
24740 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 void.** this, ea
24750 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 ch thread can ob
24760 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 tain exclusive u
24770 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 se of the [datab
24780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
24790 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 D.** by invoking
247a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
247b0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f enter]([sqlite3_
247c0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 db_mutex](D)) be
247d0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a fore beginning.*
247e0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 * to use D and i
247f0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
24800 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 _mutex_leave]([s
24810 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
24820 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c (D)) after.** al
24830 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 l calls to the i
24840 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 nterfaces listed
24850 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 here are comple
24860 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ted..**.** If an
24870 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
24880 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
24890 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
248a0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
248b0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
248c0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
248d0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
248e0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
248f0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
24900 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
24910 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
24920 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
24930 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
24940 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *db);.int sqlite
24950 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
24960 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
24970 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
24980 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
24990 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 te3*);.const voi
249a0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
249b0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 g16(sqlite3*);.c
249c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
249d0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a e3_errstr(int);.
249e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
249f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f SQL Statement O
24a00 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
24a10 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
24a20 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
24a30 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
24a40 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
24a50 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
24a60 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
24a70 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
24a80 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
24a90 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
24aa0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
24ab0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
24ac0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
24ad0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
24ae0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
24af0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
24b00 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
24b10 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
24b20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
24b30 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
24b40 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
24b50 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
24b60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
24b70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
24b80 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
24b90 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
24ba0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
24bb0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
24bc0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
24bd0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
24be0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
24bf0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
24c00 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
24c10 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
24c20 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
24c30 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
24c40 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
24c50 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
24c60 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
24c70 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
24c80 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
24c90 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
24ca0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
24cb0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
24cc0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
24cd0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
24ce0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
24cf0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
24d00 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
24d10 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
24d20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
24d30 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
24d40 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
24d50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
24d60 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
24d70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
24d80 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a -time Limits.**.
24d90 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 ** ^(This interf
24da0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
24db0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
24dc0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
24dd0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
24de0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
24df0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
24e00 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
24e10 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
24e20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
24e30 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
24e40 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
24e50 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
24e60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
24e70 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
24e80 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
24e90 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
24ea0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
24eb0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
24ec0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
24ed0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
24ee0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
24ef0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
24f00 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a onstruct.)^.**.*
24f10 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
24f20 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
24f30 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
24f40 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
24f50 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 ..** ^(For each
24f60 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 limit category S
24f70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e QLITE_LIMIT_<i>N
24f80 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 AME</i> there is
24f90 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c a .** [limits |
24fa0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
24fb0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d d].** set at com
24fc0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 pile-time by a C
24fd0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
24fe0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c cro called.** [l
24ff0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d imits | SQLITE_M
25000 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e AX_<i>NAME</i>].
25010 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
25020 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
25030 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
25040 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 AX_".))^.** ^Att
25050 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 empts to increas
25060 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 e a limit above
25070 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 its hard upper b
25080 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 ound are.** sile
25090 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 ntly truncated t
250a0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 o the hard upper
250b0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 bound..**.** ^R
250c0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
250d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
250e0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 limit was change
250f0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 d, the .** [sqli
25100 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 te3_limit()] int
25110 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
25120 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
25130 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 f the limit..**
25140 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 ^Hence, to find
25150 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
25160 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 e of a limit wit
25170 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 hout changing it
25180 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f ,.** simply invo
25190 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ke this interfac
251a0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 e with the third
251b0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 parameter set t
251c0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d o -1..**.** Run-
251d0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
251e0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
251f0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
25200 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
25210 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
25220 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
25230 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
25240 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
25250 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
25260 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
25270 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
25280 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
25290 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
252a0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
252b0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
252c0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
252d0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
252e0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
252f0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
25300 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
25310 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
25320 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
25330 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
25340 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
25350 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
25360 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
25370 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
25380 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
25390 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
253a0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
253b0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
253c0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
253d0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
253e0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
253f0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
25400 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
25410 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
25420 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
25430 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
25440 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
25450 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
25460 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
25470 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
25480 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
25490 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
254a0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
254b0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
254c0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
254d0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
254e0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
254f0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
25500 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
25510 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
25520 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 eases..*/.int sq
25530 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
25540 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
25550 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
25560 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
25570 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
25580 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
25590 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
255a0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
255b0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
255c0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
255d0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
255e0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
255f0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
25600 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
25610 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
25620 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
25630 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
25640 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
25650 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
25660 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
25670 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
25680 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
25690 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
256a0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
256b0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
256c0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
256d0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e LIMIT_LENGTH]] ^
256e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
256f0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a T_LENGTH</dt>.**
25700 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
25710 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 size of any str
25720 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 ing or BLOB or t
25730 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 able row, in byt
25740 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 es.<dd>)^.**.**
25750 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 [[SQLITE_LIMIT_S
25760 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 QL_LENGTH]] ^(<d
25770 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
25780 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
25790 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
257a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
257b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e QL statement, in
257c0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a bytes.</dd>)^.*
257d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
257e0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c MIT_COLUMN]] ^(<
257f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
25800 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
25810 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
25820 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
25830 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
25840 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
25850 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
25860 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
25870 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
25880 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
25890 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
258a0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
258b0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
258c0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
258d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 [[SQLITE_LIMIT_E
258e0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 XPR_DEPTH]] ^(<d
258f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
25900 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
25910 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
25920 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
25930 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
25940 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
25950 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
25960 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
25970 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 D_SELECT]] ^(<dt
25980 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
25990 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
259a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
259b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
259c0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
259d0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
259e0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ment.</dd>)^.**.
259f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
25a00 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 T_VDBE_OP]] ^(<d
25a10 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
25a20 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
25a30 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
25a40 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
25a50 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
25a60 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
25a70 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
25a80 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
25a90 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 tatement. This
25aa0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 limit is not cur
25ab0 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 rently.** enforc
25ac0 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 ed, though that
25ad0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 might be added i
25ae0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
25af0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
25b00 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a te.</dd>)^.**.**
25b10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
25b20 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e FUNCTION_ARG]] ^
25b30 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
25b40 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f T_FUNCTION_ARG</
25b50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
25b60 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
25b70 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 arguments on a
25b80 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e function.</dd>)^
25b90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
25ba0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d LIMIT_ATTACHED]]
25bb0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
25bc0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
25bd0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
25be0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b imum number of [
25bf0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 ATTACH | attache
25c00 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c d databases].)^<
25c10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
25c20 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
25c30 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a ATTERN_LENGTH]].
25c40 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
25c50 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
25c60 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
25c70 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
25c80 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
25c90 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
25ca0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f to the [LIKE] o
25cb0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 r.** [GLOB] oper
25cc0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ators.</dd>)^.**
25cd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
25ce0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
25cf0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ER]].** ^(<dt>SQ
25d00 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
25d10 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
25d20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
25d30 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 um index number
25d40 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 of any [paramete
25d50 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 r] in an SQL sta
25d60 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 tement.)^.**.**
25d70 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 [[SQLITE_LIMIT_T
25d80 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e RIGGER_DEPTH]] ^
25d90 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
25da0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c T_TRIGGER_DEPTH<
25db0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
25dc0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
25dd0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 recursion for t
25de0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a riggers.</dd>)^.
25df0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
25e00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
25e10 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
25e20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
25e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
25e40 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
25e50 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
25e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
25e70 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
25e80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
25e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
25ea0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
25eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
25ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
25ed0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
25ee0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
25ef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
25f00 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
25f10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
25f20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
25f30 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
25f40 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
25f50 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
25f60 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
25f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
25f80 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
25f90 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
25fa0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
25fb0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
25fc0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
25fd0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
25fe0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
25ff0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
26000 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
26010 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 10../*.** CA
26020 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e PI3REF: Compilin
26030 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 g An SQL Stateme
26040 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 nt.** KEYWORDS:
26050 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 {SQL statement c
26060 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 ompiler}.**.** T
26070 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c o execute an SQL
26080 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 query, it must
26090 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
260a0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
260b0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
260c0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
260d0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
260e0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
260f0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 ent, "db", is a
26100 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
26110 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 tion] obtained f
26120 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 rom a.** prior s
26130 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
26140 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
26150 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
26160 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 n_v2()] or.** [s
26170 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
26180 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
26190 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
261a0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c not have been cl
261b0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
261c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
261d0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
261e0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
261f0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
26200 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
26210 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
26220 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
26230 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 pare() and sqlit
26240 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a e3_prepare_v2().
26250 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
26260 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c e UTF-8, and sql
26270 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
26280 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
26290 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 pare16_v2().** u
262a0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
262b0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 ^If the nByte a
262c0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 rgument is less
262d0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 than zero, then
262e0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 zSql is read up
262f0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 to the.** first
26300 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
26310 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f ^If nByte is no
26320 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
26330 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d it is the maxim
26340 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 um.** number of
26350 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
26360 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 zSql. ^When nB
26370 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
26380 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c ive, the.** zSql
26390 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 string ends at
263a0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 either the first
263b0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 '\000' or '\u00
263c0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 00' character or
263d0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 .** the nByte-th
263e0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 byte, whichever
263f0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 comes first. If
26400 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
26410 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 s.** that the su
26420 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 pplied string is
26430 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c nul-terminated,
26440 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 then there is a
26450 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 small.** perfor
26460 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 mance advantage
26470 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 to be gained by
26480 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
26490 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
264a0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 ** is equal to t
264b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
264c0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
264d0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
264e0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
264f0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 ul-terminator by
26500 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 tes as this save
26510 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 s SQLite from ha
26520 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 ving to.** make
26530 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e a copy of the in
26540 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a put string..**.*
26550 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 * ^If pzTail is
26560 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
26570 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
26580 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
26590 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
265a0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
265b0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
265c0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
265d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
265e0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
265f0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
26600 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
26610 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
26620 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
26630 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
26640 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 led..**.** ^*ppS
26650 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
26660 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
26670 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
26680 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
26690 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
266a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
266b0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 tep()]. ^If the
266c0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
266d0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
266e0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 * to NULL. ^If
266f0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
26700 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
26710 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
26720 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
26730 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
26740 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
26750 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
26760 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
26770 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
26780 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
26790 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
267a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
267b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
267c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
267d0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
267e0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
267f0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
26800 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 NULL..**.** ^On
26810 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c success, the sql
26820 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 ite3_prepare() f
26830 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 amily of routine
26840 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
26850 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 _OK];.** otherwi
26860 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
26870 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
26880 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
26890 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
268a0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
268b0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
268c0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
268d0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
268e0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
268f0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
26900 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
26910 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
26920 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
26930 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
26940 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
26950 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 ..** ^In the "v2
26960 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
26970 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
26980 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
26990 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
269a0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
269b0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
269c0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
269d0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
269e0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
269f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
26a00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
26a10 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
26a20 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
26a30 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
26a40 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
26a50 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
26a60 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
26a70 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
26a80 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
26a90 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
26aa0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
26ab0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
26ac0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
26ad0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
26ae0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
26af0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
26b00 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 t again. As many
26b10 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f as [SQLITE_MAX_
26b20 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a SCHEMA_RETRY].**
26b30 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 retries will oc
26b40 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 cur before sqlit
26b50 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 e3_step() gives
26b60 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 up and returns a
26b70 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 n error..** </li
26b80 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
26b90 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
26ba0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
26bb0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
26bc0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
26bd0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
26be0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
26bf0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
26c00 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
26c10 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
26c20 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
26c30 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
26c40 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
26c50 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
26c60 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
26c70 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
26c80 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
26c90 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
26ca0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
26cb0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
26cc0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
26cd0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
26ce0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
26cf0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
26d00 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
26d10 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
26d20 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
26d30 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
26d40 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
26d50 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
26d60 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
26d70 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
26d80 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
26d90 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
26da0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
26db0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
26dc0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
26dd0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
26de0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
26df0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
26e00 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
26e10 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
26e20 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
26e30 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
26e40 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
26e50 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
26e60 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
26e70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
26e80 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
26e90 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
26ea0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
26eb0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
26ec0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
26ed0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
26ee0 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
26ef0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
26f00 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
26f10 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
26f20 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
26f30 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
26f40 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
26f50 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
26f60 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
26f70 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
26f80 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
26f90 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
26fa0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
26fb0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
26fc0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
26fd0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
26fe0 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
26ff0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a led..** </li>.**
27000 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 </ol>.*/.int sq
27010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
27020 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
27030 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
27040 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
27050 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
27060 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
27070 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
27080 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
27090 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
270a0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
270b0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
270c0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
270d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
270e0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
270f0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
27100 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
27110 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
27120 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
27130 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
27140 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
27150 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
27160 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
27170 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
27180 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
27190 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
271a0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
271b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
271c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
271d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
271e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
271f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
27200 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
27210 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
27220 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
27230 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
27240 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
27250 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
27260 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
27270 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
27280 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
27290 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
272a0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
272b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
272c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
272d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
272e0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
272f0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
27300 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
27310 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
27320 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
27330 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
27340 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
27350 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
27360 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
27370 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
27380 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
27390 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
273a0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
273b0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
273c0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
273d0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
273e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
273f0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
27400 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
27410 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
27420 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
27430 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
27440 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
27450 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
27460 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
27470 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
27480 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
27490 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
274a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
274b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
274c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
274d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
274e0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
274f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
27500 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
27510 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
27520 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
27530 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
27540 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a atement SQL.**.*
27550 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
27560 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
27570 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 retrieve a save
27580 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 d copy of the or
27590 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 iginal.** SQL te
275a0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 xt used to creat
275b0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 e a [prepared st
275c0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 atement] if that
275d0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a statement was.*
275e0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 * compiled using
275f0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
27600 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
27610 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
27620 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 re16_v2()]..*/.c
27630 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
27640 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 e3_sql(sqlite3_s
27650 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
27660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
27670 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
27680 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 L Statement Writ
27690 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a es The Database.
276a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
276b0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
276c0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
276d0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
276e0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
276f0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
27700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27710 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
27720 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
27730 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
27740 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
27750 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
27760 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
27770 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
27780 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
27790 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
277a0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
277b0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
277c0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
277d0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
277e0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
277f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
27800 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
27810 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
27820 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
27830 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
27840 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
27850 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
27860 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
27870 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
27880 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
27890 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
278a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
278b0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
278c0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
278d0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
278e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
278f0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
27900 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
27910 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
27920 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
27930 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
27940 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
27950 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
27960 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
27970 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
27980 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
27990 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
279a0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
279b0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
279c0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
279d0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
279e0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
279f0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
27a00 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
27a10 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
27a20 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
27a30 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
27a40 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
27a50 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
27a60 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
27a70 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
27a80 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
27a90 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
27aa0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
27ab0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
27ac0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
27ad0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
27ae0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
27af0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
27b00 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
27b10 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
27b20 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
27b30 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
27b40 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
27b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
27b60 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
27b70 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
27b80 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
27b90 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
27ba0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e s on disk..*/.in
27bb0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 t sqlite3_stmt_r
27bc0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
27bd0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
27be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
27bf0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
27c00 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
27c10 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
27c20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
27c30 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 e3_stmt_busy(S)
27c40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
27c50 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
27c60 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ) if the.** [pre
27c70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
27c80 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 S has been step
27c90 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 ped at least onc
27ca0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c e using .** [sql
27cb0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 ite3_step(S)] bu
27cc0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f t has not run to
27cd0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f completion and/
27ce0 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 or has not .** b
27cf0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 een reset using
27d00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
27d10 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 )]. ^The sqlite
27d20 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 3_stmt_busy(S).*
27d30 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
27d40 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 rns false if S i
27d50 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
27d60 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 . If S is not a
27d70 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 .** NULL pointe
27d80 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 r and is not a p
27d90 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 ointer to a vali
27da0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
27db0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
27dc0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
27dd0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
27de0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
27df0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a desirable..**.**
27e00 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
27e10 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 can be used in c
27e20 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 ombination [sqli
27e30 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d te3_next_stmt()]
27e40 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c .** to locate al
27e50 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 l prepared state
27e60 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 ments associated
27e70 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 with a database
27e80 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 .** connection
27e90 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 that are in need
27ea0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e of being reset.
27eb0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 This can be us
27ec0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 ed,.** for examp
27ed0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 le, in diagnosti
27ee0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 c routines to se
27ef0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 arch for prepare
27f00 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 d .** statements
27f10 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e that are holdin
27f20 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 g a transaction
27f30 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c open..*/.int sql
27f40 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 ite3_stmt_busy(s
27f50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
27f60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27f70 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
27f80 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
27f90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
27fa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
27fb0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
27fc0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
27fd0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
27fe0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
27ff0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
28000 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
28010 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
28020 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
28030 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
28040 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
28050 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
28060 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
28070 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
28080 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
28090 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
280a0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
280b0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
280c0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
280d0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
280e0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
280f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
28100 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
28110 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
28120 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
28130 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
28140 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
28150 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
28160 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
28170 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
28180 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
28190 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
281a0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
281b0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
281c0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
281d0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
281e0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
281f0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
28200 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
28210 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
28220 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
28230 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
28240 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
28250 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
28260 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
28270 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
28280 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
28290 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 An internal mute
282a0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 x is held for a
282b0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
282c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
282d0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 t but no mutex i
282e0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e s held for an un
282f0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
28300 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
28310 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 t. If SQLite is
28320 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 compiled to be
28330 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a single-threaded.
28340 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 ** (with [SQLITE
28350 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 _THREADSAFE=0] a
28360 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 nd with [sqlite3
28370 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 _threadsafe()] r
28380 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f eturning 0).** o
28390 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 r if SQLite is r
283a0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 un in one of red
283b0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 uced mutex modes
283c0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [SQLITE_CON
283d0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
283e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
283f0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
28400 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 .** then there i
28410 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e s no distinction
28420 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
28430 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
28440 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
28450 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 lue objects and
28460 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 they can be used
28470 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 interchangeably
28480 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
28490 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 or maximum code
284a0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 portability it i
284b0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
284c0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a at applications.
284d0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 ** still make th
284e0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 e distinction be
284f0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
28500 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
28510 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
28520 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 objects even wh
28530 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 en not strictly
28540 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
28550 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
28560 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 ue objects that
28570 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 are passed as pa
28580 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 rameters into th
28590 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
285a0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 ion of [applicat
285b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
285c0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 functions] are p
285d0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 rotected..** ^Th
285e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
285f0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
28600 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
28610 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
28620 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a s unprotected..*
28630 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 * Unprotected sq
28640 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
28650 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 cts may only be
28660 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 used with.** [sq
28670 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
28680 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
28690 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
286a0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
286b0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 3_value_blob | s
286c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
286d0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a e()] family of.*
286e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 * interfaces req
286f0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 uire protected s
28700 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
28710 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ects..*/.typedef
28720 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 struct Mem sqli
28730 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a te3_value;../*.*
28740 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
28750 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
28760 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
28770 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 e context in whi
28780 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 ch an SQL functi
28790 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 on executes is s
287a0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 tored in an.** s
287b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
287c0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 bject. ^A point
287d0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 er to an sqlite3
287e0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a _context object.
287f0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 ** is always fir
28800 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
28810 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
28820 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
28830 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c ns]..** The appl
28840 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
28850 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
28860 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
28870 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f pass this.** po
28880 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e inter through in
28890 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c to calls to [sql
288a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 ite3_result_int
288b0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 | sqlite3_result
288c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
288d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
288e0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f xt()], [sqlite3_
288f0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a user_data()],.**
28900 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
28910 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 t_db_handle()],
28920 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 [sqlite3_get_aux
28930 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f data()],.** and/
28940 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f or [sqlite3_set_
28950 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 auxdata()]..*/.t
28960 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
28970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 lite3_context sq
28980 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a lite3_context;..
28990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
289a0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 Binding Values T
289b0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 o Prepared State
289c0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ments.** KEYWORD
289d0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 S: {host paramet
289e0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 er} {host parame
289f0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 ters} {host para
28a00 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b meter name}.** K
28a10 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 EYWORDS: {SQL pa
28a20 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 rameter} {SQL pa
28a30 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d rameters} {param
28a40 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a eter binding}.**
28a50 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c .** ^(In the SQL
28a60 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
28a70 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
28a80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
28a90 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
28aa0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 ,.** literals ma
28ab0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 y be replaced by
28ac0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 a [parameter] t
28ad0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 hat matches one
28ae0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 of following.**
28af0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a templates:.**.**
28b00 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
28b10 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
28b20 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
28b30 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
28b40 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
28b50 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 >.**.** In the t
28b60 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 emplates above,
28b70 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 NNN represents a
28b80 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 n integer litera
28b90 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 l,.** and VVV re
28ba0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 presents an alph
28bb0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 anumeric identif
28bc0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c ier.)^ ^The val
28bd0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ues of these.**
28be0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f parameters (also
28bf0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 called "host pa
28c00 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f rameter names" o
28c10 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 r "SQL parameter
28c20 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
28c30 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
28c40 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
28c50 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
28c60 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 re..**.** ^The f
28c70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
28c80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
28c90 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
28ca0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
28cb0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
28cc0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
28cd0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
28ce0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
28cf0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
28d00 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
28d10 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 * ^The second ar
28d20 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
28d30 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 dex of the SQL p
28d40 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 arameter to be s
28d50 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 et..** ^The left
28d60 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 most SQL paramet
28d70 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
28d80 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 of 1. ^When the
28d90 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
28da0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
28db0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
28dc0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
28dd0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
28de0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
28df0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
28e00 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
28e10 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 rence..** ^The i
28e20 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 ndex for named p
28e30 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 arameters can be
28e40 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 looked up using
28e50 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
28e60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
28e70 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 index()] API if
28e80 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 desired. ^The i
28e90 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
28ea0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
28eb0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
28ec0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 N..** ^The NNN v
28ed0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
28ee0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
28ef0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
28f00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
28f10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
28f20 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
28f30 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
28f40 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 )..**.** ^The th
28f50 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
28f60 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e the value to bin
28f70 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 d to the paramet
28f80 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
28f90 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
28fa0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
28fb0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
28fc0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
28fd0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
28fe0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 d_blob() is a NU
28ff0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
29000 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
29010 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 eter.** is ignor
29020 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 ed and the end r
29030 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d esult is the sam
29040 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e e as sqlite3_bin
29050 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 d_null()..**.**
29060 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
29070 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
29080 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
29090 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
290a0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
290b0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
290c0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
290d0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
290e0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
290f0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
29100 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
29110 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
29120 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
29130 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
29140 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
29150 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
29160 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
29170 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 _text16().** is
29180 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
29190 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
291a0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
291b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
291c0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
291d0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
291e0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 r..** If the fou
291f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
29200 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
29210 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 ob() is negative
29220 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 , then.** the be
29230 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
29240 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e ned..** If a non
29250 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 -negative fourth
29260 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
29270 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 ovided to sqlite
29280 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 3_bind_text().**
29290 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
292a0 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 _text16() then t
292b0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 hat parameter mu
292c0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
292d0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 ffset.** where t
292e0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
292f0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 r would occur as
29300 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e suming the strin
29310 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 g were NUL.** te
29320 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
29330 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
29340 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f occur at byte o
29350 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e ffsets less than
29360 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f .** the value o
29370 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
29380 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 ameter then the
29390 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
293a0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 value will.** c
293b0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
293c0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c NULs. The resul
293d0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
293e0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e involving strin
293f0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 gs.** with embed
29400 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
29410 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
29420 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
29430 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
29440 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
29450 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e _bind_text(), an
29460 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e d.** sqlite3_bin
29470 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 d_text16() is a
29480 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
29490 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
294a0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
294b0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
294c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
294d0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
294e0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
294f0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
29500 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
29510 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
29520 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
29530 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 3_bind_blob(),.*
29540 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
29550 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 ext(), or sqlite
29560 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
29570 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 fails. .** ^If
29580 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
29590 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
295a0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
295b0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
295c0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
295d0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
295e0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
295f0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
29600 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
29610 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
29620 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
29630 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
29640 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
29650 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
29660 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
29670 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
29680 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
29690 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
296a0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
296b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
296c0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
296d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
296e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
296f0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
29700 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
29710 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
29720 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
29730 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
29740 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
29750 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
29760 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
29770 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
29780 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
29790 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
297a0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
297b0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
297c0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
297d0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
297e0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
297f0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
29800 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
29810 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
29820 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
29830 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
29840 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
29850 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
29860 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
29870 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
29880 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 BLOB..**.** ^If
29890 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
298a0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
298b0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
298c0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
298d0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
298e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
298f0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
29900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29910 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
29920 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
29930 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
29940 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
29950 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
29960 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
29970 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
29980 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
29990 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
299a0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
299b0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
299c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
299d0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
299e0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
299f0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
29a00 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
29a10 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
29a20 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
29a30 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
29a40 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
29a50 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
29a60 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
29a70 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
29a80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
29a90 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
29aa0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
29ab0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
29ac0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
29ad0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
29ae0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
29af0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
29b00 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 g..** ^[SQLITE_R
29b10 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
29b20 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
29b30 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
29b40 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
29b50 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
29b60 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
29b70 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
29b80 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
29b90 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
29ba0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
29bb0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
29bc0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
29bd0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
29be0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
29bf0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
29c00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
29c10 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
29c20 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
29c30 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
29c40 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
29c50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
29c60 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
29c70 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
29c80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
29c90 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
29ca0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 t*, int, int);.i
29cb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
29cc0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
29cd0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 mt*, int, sqlite
29ce0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 3_int64);.int sq
29cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 lite3_bind_null(
29d00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
29d10 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
29d20 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
29d30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
29d40 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 onst char*, int
29d50 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
29d60 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
29d70 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
29d80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
29d90 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
29da0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
29db0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
29dc0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
29dd0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
29de0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
29df0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
29e00 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
29e10 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
29e20 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
29e30 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
29e40 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
29e50 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ters.**.** ^This
29e60 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
29e70 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
29e80 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
29e90 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
29ea0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
29eb0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
29ec0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
29ed0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
29ee0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
29ef0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
29f00 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
29f10 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
29f20 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
29f30 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
29f40 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
29f50 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
29f60 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
29f70 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
29f80 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
29f90 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
29fa0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
29fb0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
29fc0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
29fd0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
29fe0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
29ff0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
2a000 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
2a010 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
2a020 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
2a030 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
2a040 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
2a050 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
2a060 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
2a070 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
2a080 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2a090 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2a0a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2a0b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2a0c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2a0d0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2a0e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2a0f0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2a100 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2a110 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2a120 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
2a130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a140 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
2a150 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a t Parameter.**.*
2a160 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
2a170 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2a180 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(P,N) interfac
2a190 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 e returns.** the
2a1a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 name of the N-t
2a1b0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 h [SQL parameter
2a1c0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 ] in the [prepar
2a1d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
2a1e0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 .** ^(SQL parame
2a1f0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
2a200 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
2a210 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
2a220 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
2a230 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
2a240 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
2a250 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
2a260 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
2a270 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
2a280 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
2a290 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
2a2a0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
2a2b0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
2a2c0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
2a2d0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 the name.)^.**
2a2e0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 ^Parameters of t
2a2f0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
2a300 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
2a310 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
2a320 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
2a330 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 referred to as "
2a340 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e nameless" or "an
2a350 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
2a360 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rs"..**.** ^The
2a370 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
2a380 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
2a390 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
2a3a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c *.** ^If the val
2a3b0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 ue N is out of r
2a3c0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e ange or if the N
2a3d0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 -th parameter is
2a3e0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 .** nameless, th
2a3f0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 en NULL is retur
2a400 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ned. ^The retur
2a410 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a ned string is.**
2a420 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 always in UTF-8
2a430 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 encoding even i
2a440 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 f the named para
2a450 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 meter was.** ori
2a460 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 ginally specifie
2a470 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b d as UTF-16 in [
2a480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a490 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 6()] or.** [sqli
2a4a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2a4b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
2a4c0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2a4d0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2a4e0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2a4f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2a500 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
2a510 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
2a520 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2a530 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 ex()]..*/.const
2a540 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 char *sqlite3_bi
2a550 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2a560 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2a570 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
2a580 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
2a590 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
2a5a0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a h A Given Name.*
2a5b0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
2a5c0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
2a5d0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
2a5e0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
2a5f0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
2a600 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
2a610 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
2a620 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
2a630 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2a640 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2a650 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
2a660 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
2a670 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
2a680 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
2a690 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
2a6a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
2a6b0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
2a6c0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
2a6d0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
2a6e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
2a6f0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
2a700 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
2a710 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a720 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
2a730 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2a740 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2a750 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
2a760 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2a770 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2a780 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2a790 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2a7a0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
2a7b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
2a7c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 arameter_index(s
2a7d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f qlite3_stmt*, co
2a7e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
2a7f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a800 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e F: Reset All Bin
2a810 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 dings On A Prepa
2a820 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a red Statement.**
2a830 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f .** ^Contrary to
2a840 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f the intuition o
2a850 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 f many, [sqlite3
2a860 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e _reset()] does n
2a870 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 ot reset.** the
2a880 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2a890 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f ob | bindings] o
2a8a0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2a8b0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 atement]..** ^Us
2a8c0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
2a8d0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 o reset all host
2a8e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e parameters to N
2a8f0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
2a900 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2a910 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
2a920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2a930 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f EF: Number Of Co
2a940 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c lumns In A Resul
2a950 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 t Set.**.** ^Ret
2a960 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
2a970 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
2a980 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
2a990 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
2a9a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a9b0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 nt]. ^This routi
2a9c0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
2a9d0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a pStmt is an SQL.
2a9e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ** statement tha
2a9f0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 t does not retur
2aa00 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d n data (for exam
2aa10 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
2aa20 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2aa30 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
2aa40 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 count()].*/.int
2aa50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2aa60 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2aa70 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2aa80 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
2aa90 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
2aaa0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e sult Set.**.** ^
2aab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
2aac0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
2aad0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
2aae0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
2aaf0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
2ab00 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
2ab10 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 ] statement. ^T
2ab20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
2ab30 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
2ab40 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2ab50 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
2ab60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
2ab70 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
2ab80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2ab90 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
2aba0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2abb0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
2abc0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
2abd0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 . ^The first pa
2abe0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
2abf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2ac00 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
2ac10 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
2ac20 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e CT] statement. ^
2ac30 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
2ac40 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
2ac50 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e olumn number. ^
2ac60 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
2ac70 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
2ac80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
2ac90 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
2aca0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
2acb0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
2acc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2acd0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
2ace0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
2acf0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
2ad00 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
2ad10 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
2ad20 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
2ad30 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
2ad40 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2ad50 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
2ad60 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
2ad70 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
2ad80 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
2ad90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2ada0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
2adb0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
2adc0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
2add0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 .**.** ^If sqlit
2ade0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
2adf0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
2ae00 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
2ae10 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
2ae20 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
2ae30 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
2ae40 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
2ae50 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
2ae60 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
2ae70 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
2ae80 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
2ae90 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
2aea0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
2aeb0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
2aec0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
2aed0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
2aee0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
2aef0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
2af00 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
2af10 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
2af20 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
2af30 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
2af40 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
2af50 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
2af60 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f the next..*/.co
2af70 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2af80 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 3_column_name(sq
2af90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2afa0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 N);.const void
2afb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2afc0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2afd0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
2afe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2aff0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
2b000 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2b010 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2b020 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
2b030 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
2b040 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
2b050 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
2b060 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
2b070 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
2b080 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
2b090 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
2b0a0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
2b0b0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
2b0c0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
2b0d0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
2b0e0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
2b0f0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
2b100 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
2b110 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
2b120 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
2b130 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
2b140 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
2b150 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
2b160 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2b170 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
2b180 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
2b190 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
2b1a0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
2b1b0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
2b1c0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2b1d0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
2b1e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2b1f0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
2b200 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
2b210 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2b220 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2b230 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2b240 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2b250 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2b260 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2b270 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2b280 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2b290 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2b2a0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
2b2b0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
2b2c0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
2b2d0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
2b2e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
2b2f0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
2b300 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
2b310 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
2b320 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
2b330 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
2b340 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
2b350 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
2b360 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
2b370 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
2b380 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2b390 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
2b3a0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2b3b0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
2b3c0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
2b3d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
2b3e0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
2b3f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
2b400 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
2b410 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
2b420 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
2b430 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
2b440 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
2b450 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
2b460 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
2b470 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
2b480 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
2b490 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
2b4a0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
2b4b0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
2b4c0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
2b4d0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2b4e0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
2b4f0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
2b500 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
2b510 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
2b520 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
2b530 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
2b540 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
2b550 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
2b560 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
2b570 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
2b580 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
2b590 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
2b5a0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
2b5b0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
2b5c0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
2b5d0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
2b5e0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
2b5f0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
2b600 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
2b610 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
2b620 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
2b630 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
2b640 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
2b650 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
2b660 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
2b670 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
2b680 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
2b690 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
2b6a0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
2b6b0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
2b6c0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
2b6d0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2b6e0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2b6f0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
2b700 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
2b710 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
2b720 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
2b730 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
2b740 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
2b750 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
2b760 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
2b770 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
2b780 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
2b790 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
2b7a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2b7b0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
2b7c0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
2b7d0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
2b7e0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
2b7f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
2b800 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
2b810 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
2b820 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
2b830 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2b840 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
2b850 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2b860 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2b870 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2b880 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2b890 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2b8a0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2b8b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2b8c0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
2b8d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2b8e0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
2b8f0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2b900 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2b910 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
2b920 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2b930 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2b940 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2b950 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2b960 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2b970 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2b980 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2b990 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2b9a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2b9b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2b9c0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2b9d0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2b9e0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 Result.**.** ^(T
2b9f0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2ba00 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
2ba10 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2ba20 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
2ba30 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
2ba40 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2ba50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
2ba60 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
2ba70 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
2ba80 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
2ba90 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
2baa0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
2bab0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2bac0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
2bad0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
2bae0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
2baf0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
2bb00 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2bb10 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2bb20 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
2bb30 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2bb40 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
2bb50 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2bb60 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
2bb70 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2bb80 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
2bb90 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
2bba0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
2bbb0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2bbc0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
2bbd0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
2bbe0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
2bbf0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
2bc00 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
2bc10 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
2bc20 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
2bc30 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
2bc40 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
2bc50 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
2bc60 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
2bc70 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
2bc80 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
2bc90 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
2bca0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
2bcb0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
2bcc0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
2bcd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2bce0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
2bcf0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
2bd00 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
2bd10 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
2bd20 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
2bd30 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
2bd40 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
2bd50 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
2bd60 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
2bd70 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
2bd80 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
2bd90 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
2bda0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
2bdb0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
2bdc0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
2bdd0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
2bde0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
2bdf0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
2be00 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
2be10 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
2be20 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
2be30 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
2be40 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
2be50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
2be60 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
2be70 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2be80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2be90 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
2bea0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2beb0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2bec0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
2bed0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
2bee0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
2bef0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2bf00 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
2bf10 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
2bf20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2bf30 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
2bf40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2bf50 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
2bf60 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2bf70 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
2bf80 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
2bf90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2bfa0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
2bfb0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
2bfc0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
2bfd0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
2bfe0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
2bff0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
2c000 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
2c010 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
2c020 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
2c030 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
2c040 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
2c050 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
2c060 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
2c070 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
2c080 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
2c090 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2c0a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2c0b0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2c0c0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
2c0d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
2c0e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2c0f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2c100 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
2c110 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
2c120 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
2c130 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2c140 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
2c150 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
2c160 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
2c170 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
2c180 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
2c190 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
2c1a0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2c1b0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2c1c0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
2c1d0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
2c1e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2c1f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
2c200 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
2c210 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
2c220 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
2c230 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2c240 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
2c250 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
2c260 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2c270 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
2c280 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
2c290 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
2c2a0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
2c2b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
2c2c0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
2c2d0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
2c2e0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
2c2f0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
2c300 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
2c310 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
2c320 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
2c330 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
2c340 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
2c350 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2c360 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
2c370 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
2c380 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
2c390 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
2c3a0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
2c3b0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
2c3c0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 an.** explicit t
2c3d0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
2c3e0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
2c3f0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
2c400 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
2c410 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
2c420 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d ^[SQLITE_DONE] m
2c430 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
2c440 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
2c450 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
2c460 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
2c470 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2c480 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2c490 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
2c4a0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
2c4b0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
2c4c0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
2c4d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
2c4e0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
2c4f0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
2c500 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2c510 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e l state..**.** ^
2c520 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2c530 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
2c540 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
2c550 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
2c560 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
2c570 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
2c580 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
2c590 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
2c5a0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
2c5b0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
2c5c0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
2c5d0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
2c5e0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
2c5f0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
2c600 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2c610 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
2c620 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
2c630 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
2c640 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2c650 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
2c660 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
2c670 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
2c680 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
2c690 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
2c6a0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
2c6b0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
2c6c0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
2c6d0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
2c6e0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
2c6f0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
2c700 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2c710 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 errmsg()]..** ^W
2c720 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
2c730 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
2c740 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
2c750 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
2c760 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
2c770 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
2c780 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
2c790 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
2c7a0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
2c7b0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
2c7c0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2c7d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
2c7e0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2c7f0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 tatement]. ^In
2c800 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2c810 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
2c820 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
2c830 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
2c840 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
2c850 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
2c860 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
2c870 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2c880 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
2c890 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
2c8a0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
2c8b0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
2c8c0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
2c8d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2c8e0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
2c8f0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
2c900 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
2c910 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
2c920 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
2c930 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
2c940 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
2c950 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
2c960 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
2c970 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
2c980 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2c990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2c9a0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
2c9b0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
2c9c0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
2c9d0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
2c9e0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 ..**.** For all
2c9f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2ca00 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 te up to and inc
2ca10 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c luding 3.6.23.1,
2ca20 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 a call to.** [s
2ca30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2ca40 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 was required aft
2ca50 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
2ca60 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 ) returned anyth
2ca70 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 ing.** other tha
2ca80 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 n [SQLITE_ROW] b
2ca90 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 efore any subseq
2caa0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 uent invocation
2cab0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 of.** sqlite3_st
2cac0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 ep(). Failure t
2cad0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 o reset the prep
2cae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
2caf0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
2cb00 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 3_reset()] would
2cb10 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 result in an [S
2cb20 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 QLITE_MISUSE] re
2cb30 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c turn from.** sql
2cb40 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 ite3_step(). Bu
2cb50 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 t after version
2cb60 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 3.6.23.1, sqlite
2cb70 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
2cb80 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
2cb90 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
2cba0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
2cbb0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
2cbc0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
2cbd0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
2cbe0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
2cbf0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
2cc00 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
2cc10 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
2cc20 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
2cc30 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
2cc40 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
2cc50 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
2cc60 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
2cc70 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
2cc80 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
2cc90 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
2cca0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
2ccb0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
2ccc0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
2ccd0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
2cce0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
2ccf0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
2cd00 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2cd10 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
2cd20 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
2cd30 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
2cd40 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
2cd50 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
2cd60 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
2cd70 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
2cd80 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
2cd90 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
2cda0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
2cdb0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
2cdc0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2cdd0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2cde0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
2cdf0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
2ce00 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
2ce10 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
2ce20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
2ce30 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
2ce40 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
2ce50 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
2ce60 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
2ce70 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
2ce80 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
2ce90 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
2cea0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
2ceb0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
2cec0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
2ced0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
2cee0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2cef0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2cf00 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
2cf10 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
2cf20 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
2cf30 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2cf40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2cf50 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
2cf60 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
2cf70 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2cf80 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
2cf90 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
2cfa0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2cfb0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
2cfc0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2cfd0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
2cfe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2cff0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
2d000 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2d010 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
2d020 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
2d030 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 ult set.**.** ^T
2d040 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2d050 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
2d060 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
2d070 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2d080 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
2d090 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2d0a0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
2d0b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2d0c0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
2d0d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2d0e0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
2d0f0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
2d100 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
2d110 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
2d120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
2d130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d140 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
2d150 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
2d160 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2d170 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
2d180 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2d190 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
2d1a0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
2d1b0 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
2d1c0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
2d1d0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2d1e0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2d1f0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
2d200 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2d210 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2d220 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
2d230 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2d240 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2d250 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
2d260 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
2d270 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
2d280 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2d290 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2d2a0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
2d2b0 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
2d2c0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
2d2d0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
2d2e0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
2d2f0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
2d300 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
2d310 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
2d320 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
2d330 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
2d340 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
2d350 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2d360 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2d370 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 _count()].*/.int
2d380 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2d390 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2d3a0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2d3b0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
2d3c0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
2d3d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
2d3e0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
2d3f0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
2d400 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
2d410 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
2d420 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
2d430 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2d440 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
2d450 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
2d460 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
2d470 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
2d480 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
2d490 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
2d4a0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
2d4b0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
2d4c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
2d4d0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
2d4e0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
2d4f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
2d500 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
2d510 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
2d520 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
2d530 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
2d540 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
2d550 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
2d560 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
2d570 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
2d580 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
2d590 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
2d5a0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
2d5b0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
2d5c0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
2d5d0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
2d5e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
2d5f0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
2d600 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
2d610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
2d620 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
2d630 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
2d640 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
2d650 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
2d660 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
2d670 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2d680 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
2d690 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
2d6a0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
2d6b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2d6c0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
2d6d0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
2d6e0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
2d6f0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
2d700 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2d710 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
2d720 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
2d730 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
2d740 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2d750 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2d760 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
2d770 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
2d780 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
2d790 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
2d7a0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
2d7b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2d7c0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2d7d0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2d7e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2d7f0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2d800 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2d810 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2d820 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2d830 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2d840 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2d850 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2d860 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2d870 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2d880 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2d890 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2d8a0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2d8b0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2d8c0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
2d8d0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2d8e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2d8f0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2d900 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
2d910 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2d920 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
2d930 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
2d940 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2d950 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
2d960 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
2d970 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2d980 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
2d990 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
2d9a0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
2d9b0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
2d9c0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
2d9d0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2d9e0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
2d9f0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
2da00 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
2da10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2da20 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2da30 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2da40 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2da50 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
2da60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2da70 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
2da80 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
2da90 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
2daa0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
2dab0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
2dac0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2dad0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
2dae0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2daf0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2db00 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
2db10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2db20 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
2db30 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2db40 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2db50 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
2db60 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2db70 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
2db80 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2db90 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2dba0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2dbb0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
2dbc0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
2dbd0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
2dbe0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2dbf0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
2dc00 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2dc10 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2dc20 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2dc30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2dc40 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
2dc50 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
2dc60 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
2dc70 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
2dc80 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
2dc90 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
2dca0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2dcb0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2dcc0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2dcd0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2dce0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2dcf0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2dd00 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2dd10 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2dd20 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2dd30 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2dd40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2dd50 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2dd60 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2dd70 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2dd80 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2dd90 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2dda0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2ddb0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2ddc0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2ddd0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2dde0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2ddf0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2de00 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2de10 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2de20 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2de30 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2de40 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2de50 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2de60 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2de70 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2de80 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2de90 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2dea0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2deb0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2dec0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2ded0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2dee0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2def0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2df00 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2df10 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2df20 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2df30 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2df40 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2df50 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2df60 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2df70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2df80 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2df90 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2dfa0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2dfb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2dfc0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2dfd0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2dfe0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2dff0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2e000 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2e010 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2e020 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2e030 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2e040 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2e050 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2e060 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2e070 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2e080 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2e090 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2e0a0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2e0b0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2e0c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2e0d0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2e0e0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2e0f0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2e100 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2e110 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2e120 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2e130 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2e140 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2e150 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2e160 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2e170 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2e180 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2e190 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2e1a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2e1b0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2e1c0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2e1d0 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2e1e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2e1f0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2e200 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2e210 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2e220 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2e230 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2e240 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2e250 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2e260 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2e270 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2e280 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2e290 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2e2a0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2e2b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2e2c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2e2d0 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2e2e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2e2f0 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2e300 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2e310 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2e320 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2e330 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2e340 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2e350 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2e360 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2e370 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2e380 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2e390 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2e3a0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2e3b0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2e3c0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2e3d0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2e3e0 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2e3f0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2e400 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2e410 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2e420 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2e430 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2e440 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2e450 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
2e460 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2e470 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2e480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2e490 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2e4a0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2e4b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2e4c0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 * ^The object re
2e4d0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2e4e0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2e4f0 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2e500 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2e510 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2e520 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
2e530 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2e540 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
2e550 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
2e560 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2e570 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2e580 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2e590 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
2e5a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2e5b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2e5c0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2e5d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2e5e0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
2e5f0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
2e600 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
2e610 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
2e620 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
2e630 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
2e640 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2e650 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
2e660 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2e670 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
2e680 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2e690 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
2e6a0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
2e6b0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2e6c0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
2e6d0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a opriate. ^For.*
2e6e0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2e6f0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2e700 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2e710 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2e720 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2e730 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2e740 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2e750 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2e760 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2e770 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2e780 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 atically. ^(The
2e790 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
2e7a0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
2e7b0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
2e7c0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
2e7d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2e7e0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2e7f0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2e800 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
2e810 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
2e820 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
2e830 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
2e840 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2e850 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2e860 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2e870 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
2e880 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
2e890 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
2e8a0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
2e8b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2e8c0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2e8d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 td> Result is a
2e8e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2e8f0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2e900 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2e910 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2e920 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2e930 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2e940 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
2e950 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2e960 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
2e970 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2e980 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2e990 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
2e9a0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
2e9b0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
2e9c0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2e9d0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
2e9e0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
2e9f0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
2ea00 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2ea10 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2ea20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
2ea30 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
2ea40 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2ea50 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2ea60 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
2ea70 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a of the float.**
2ea80 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2ea90 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2eaa0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
2eab0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 BLOB.** <tr><td
2eac0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
2ead0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
2eae0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
2eaf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
2eb00 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 XT <td> FLOA
2eb10 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d T <td> [CAST]
2eb20 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e to REAL.** <tr>
2eb30 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2eb40 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2eb50 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
2eb60 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2eb70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2eb80 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
2eb90 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
2eba0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
2ebb0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2ebc0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a [CAST] to REAL.*
2ebd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2ebe0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
2ebf0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
2ec00 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
2ec10 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
2ec20 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
2ec30 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ote>)^.**.** The
2ec40 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
2ec50 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
2ec60 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
2ec70 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
2ec80 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
2ec90 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
2eca0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
2ecb0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2ecc0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
2ecd0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
2ece0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
2ecf0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
2ed00 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
2ed10 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
2ed20 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
2ed30 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
2ed40 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
2ed50 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
2ed60 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
2ed70 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
2ed80 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
2ed90 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
2eda0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
2edb0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
2edc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2edd0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
2ede0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
2edf0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
2ee00 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
2ee10 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
2ee20 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
2ee30 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
2ee40 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
2ee50 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
2ee60 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
2ee70 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
2ee80 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
2ee90 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2eea0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
2eeb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2eec0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2eed0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2eee0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2eef0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
2ef00 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
2ef10 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
2ef20 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
2ef30 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
2ef40 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
2ef50 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
2ef60 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2ef70 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
2ef80 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2ef90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2efa0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
2efb0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
2efc0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
2efd0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
2efe0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
2eff0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2f000 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
2f010 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2f020 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
2f030 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
2f040 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
2f050 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2f060 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2f070 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2f080 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
2f090 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 ul>.**.** ^Conve
2f0a0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 rsions between U
2f0b0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d TF-16be and UTF-
2f0c0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 16le are always
2f0d0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e done in place an
2f0e0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 d do.** not inva
2f0f0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 lidate a prior p
2f100 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f ointer, though o
2f110 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e f course the con
2f120 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 tent of the buff
2f130 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 er.** that the p
2f140 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 rior pointer ref
2f150 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 erences will hav
2f160 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
2f170 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
2f180 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
2f190 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
2f1a0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
2f1b0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
2f1c0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
2f1d0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
2f1e0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
2f1f0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
2f200 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
2f210 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
2f220 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
2f230 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
2f240 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
2f250 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
2f260 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
2f270 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
2f280 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
2f290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2f2a0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
2f2b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
2f2c0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
2f2d0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
2f2e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
2f2f0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
2f300 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
2f310 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
2f320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2f330 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
2f340 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2f350 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
2f360 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
2f370 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
2f380 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
2f390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2f3a0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
2f3b0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
2f3c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2f3d0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
2f3e0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
2f3f0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
2f400 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
2f410 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
2f420 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2f430 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
2f440 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2f450 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
2f460 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
2f470 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
2f480 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
2f490 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
2f4a0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2f4b0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
2f4c0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
2f4d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2f4e0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
2f4f0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
2f500 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2f510 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
2f520 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2f530 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
2f540 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
2f550 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
2f560 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
2f570 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
2f580 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
2f590 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
2f5a0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
2f5b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
2f5c0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2f5d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2f5e0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
2f5f0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
2f600 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
2f610 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
2f620 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
2f630 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
2f640 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
2f650 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
2f660 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 rned.** from [sq
2f670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2f680 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
2f690 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
2f6a0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
2f6b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
2f6c0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
2f6d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2f6e0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2f6f0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
2f700 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
2f710 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
2f720 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
2f730 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
2f740 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
2f750 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
2f760 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
2f770 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2f780 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
2f790 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
2f7a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
2f7b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
2f7c0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
2f7d0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
2f7e0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 MEM].)^.*/.const
2f7f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2f800 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
2f810 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f820 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
2f830 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
2f840 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2f850 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
2f860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2f870 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2f880 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 , int iCol);.dou
2f890 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
2f8a0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
2f8b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2f8c0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2f8d0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
2f8e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f8f0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ol);.sqlite3_int
2f900 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
2f910 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
2f920 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2f930 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
2f940 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2f950 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
2f960 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f970 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ol);.const void
2f980 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2f990 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2f9a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2f9b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2f9c0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
2f9d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2f9e0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 );.sqlite3_value
2f9f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2fa00 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
2fa10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2fa20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2fa30 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
2fa40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2fa50 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bject.**.** ^The
2fa60 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2fa70 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
2fa80 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
2fa90 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2faa0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 tement]..** ^If
2fab0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2fac0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 evaluation of th
2fad0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f e statement enco
2fae0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 untered no error
2faf0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 s.** or if the s
2fb00 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 tatement is neve
2fb10 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 r been evaluated
2fb20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 , then sqlite3_f
2fb30 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e inalize() return
2fb40 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 s.** SQLITE_OK.
2fb50 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
2fb60 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
2fb70 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 of statement S f
2fb80 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 ailed, then.** s
2fb90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2fba0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 S) returns the a
2fbb0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
2fbc0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 r code] or.** [e
2fbd0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
2fbe0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
2fbf0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2fc00 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 (S) routine can
2fc10 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
2fc20 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a point during.**
2fc30 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 the life cycle
2fc40 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
2fc50 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 tement] S:.** be
2fc60 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 fore statement S
2fc70 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 is ever evaluat
2fc80 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 ed, after.** one
2fc90 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 or more calls t
2fca0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
2fcb0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e ()], or after an
2fcc0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 y call.** to [sq
2fcd0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
2fce0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
2fcf0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 her or not the s
2fd00 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 tatement has.**
2fd10 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 completed execut
2fd20 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f ion..**.** ^Invo
2fd30 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e king sqlite3_fin
2fd40 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c alize() on a NUL
2fd50 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
2fd60 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
2fd70 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
2fd80 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 tion must finali
2fd90 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 ze every [prepar
2fda0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
2fdb0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a order to avoid.
2fdc0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b ** resource leak
2fdd0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 s. It is a grie
2fde0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 vous error for t
2fdf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
2fe00 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 o try to use.**
2fe10 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2fe20 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
2fe30 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
2fe40 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 . Any use of a
2fe50 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2fe60 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
2fe70 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
2fe80 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 d can result in
2fe90 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a undefined and.**
2fea0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
2feb0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 avior such as se
2fec0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 gfaults and heap
2fed0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
2fee0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
2fef0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
2ff00 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2ff10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2ff20 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
2ff30 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
2ff40 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2ff50 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
2ff60 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
2ff70 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
2ff80 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
2ff90 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
2ffa0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
2ffb0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
2ffc0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
2ffd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
2ffe0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
2fff0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
30000 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
30010 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
30020 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
30030 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
30040 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
30050 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
30060 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
30070 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
30080 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
30090 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
300a0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
300b0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
300c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
300d0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
300e0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
300f0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
30100 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
30110 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
30120 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
30130 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
30140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30150 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
30160 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
30170 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
30180 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
30190 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
301a0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
301b0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
301c0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
301d0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
301e0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
301f0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
30200 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
30210 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
30220 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
30230 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
30240 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
30250 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
30260 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
30270 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
30280 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
30290 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
302a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
302b0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
302c0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
302d0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
302e0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
302f0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
30300 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
30310 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
30320 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
30330 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
30340 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
30350 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
30360 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
30370 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
30380 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
30390 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
303a0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
303b0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
303c0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
303d0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
303e0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
303f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
30400 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions}.**.** ^Th
30410 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
30420 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
30430 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
30440 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
30450 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
30460 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
30470 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
30480 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
30490 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
304a0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
304b0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
304c0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
304d0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
304e0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
304f0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
30500 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
30510 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
30520 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
30530 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
30540 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
30550 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
30560 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
30570 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
30580 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
30590 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
305a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
305b0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
305c0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
305d0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
305e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
305f0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
30600 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
30610 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
30620 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
30630 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
30640 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
30650 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
30660 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
30670 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
30680 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
30690 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
306a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
306b0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
306c0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
306d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
306e0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
306f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
30700 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
30710 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
30720 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
30730 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
30740 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
30750 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
30760 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
30770 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
30780 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
30790 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
307a0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
307b0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
307c0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
307d0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
307e0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
307f0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
30800 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
30810 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
30820 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
30830 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
30840 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
30850 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
30860 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
30870 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
30880 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
30890 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
308a0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
308b0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
308c0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
308d0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
308e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
308f0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
30900 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
30910 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
30920 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
30930 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
30940 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
30950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
30960 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
30970 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
30980 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
30990 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
309a0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
309b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
309c0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
309d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
309e0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
309f0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
30a00 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
30a10 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
30a20 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
30a30 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
30a40 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
30a50 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c eters. The appl
30a60 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 ication should s
30a70 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 et this paramete
30a80 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r to.** [SQLITE_
30a90 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 UTF16LE] if the
30aa0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
30ab0 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 ntation invokes
30ac0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
30ad0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f ue_text16le()] o
30ae0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b n an input, or [
30af0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 SQLITE_UTF16BE]
30b00 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d if the.** implem
30b10 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 entation invokes
30b20 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30b30 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 text16be()] on a
30b40 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b n input, or.** [
30b50 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 SQLITE_UTF16] if
30b60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
30b70 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 text16()] is use
30b80 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 d, or [SQLITE_UT
30b90 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 F8].** otherwise
30ba0 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c . ^The same SQL
30bb0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
30bc0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 registered mult
30bd0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 iple times using
30be0 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 .** different pr
30bf0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
30c00 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 odings, with dif
30c10 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 ferent implement
30c20 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 ations for.** ea
30c30 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 ch encoding..**
30c40 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 ^When multiple i
30c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
30c60 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
30c70 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c ion are availabl
30c80 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c e, SQLite.** wil
30c90 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 l pick the one t
30ca0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 hat involves the
30cb0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
30cc0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e data conversion
30cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
30ce0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 rth parameter ma
30cf0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 y optionally be
30d00 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 ORed with [SQLIT
30d10 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d E_DETERMINISTIC]
30d20 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 .** to signal th
30d30 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 at the function
30d40 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 will always retu
30d50 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 rn the same resu
30d60 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 lt given.** the
30d70 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 same inputs with
30d80 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 in a single SQL
30d90 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 statement. Most
30da0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
30db0 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 re.** determinis
30dc0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d tic. The built-
30dd0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 in [random()] SQ
30de0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e L function is an
30df0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a example of a.**
30e00 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 function that i
30e10 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 s not determinis
30e20 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 tic. The SQLite
30e30 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 query planner i
30e40 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 s able to.** per
30e50 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 form additional
30e60 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e optimizations on
30e70 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 deterministic f
30e80 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 unctions, so use
30e90 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
30ea0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
30eb0 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d ] flag is recomm
30ec0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 ended where poss
30ed0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ible..**.** ^(Th
30ee0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
30ef0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 r is an arbitrar
30f00 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 y pointer. The
30f10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
30f20 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
30f30 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 n can gain acces
30f40 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 s to this pointe
30f50 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 r using [sqlite3
30f60 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e _user_data()].)^
30f70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 .**.** ^The sixt
30f80 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 h, seventh and e
30f90 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 ighth parameters
30fa0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 , xFunc, xStep a
30fb0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a nd xFinal, are.*
30fc0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d * pointers to C-
30fd0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f language functio
30fe0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ns that implemen
30ff0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
31000 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
31010 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 te. ^A scalar SQ
31020 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
31030 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
31040 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 ation of the xFu
31050 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f nc.** callback o
31060 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nly; NULL pointe
31070 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 rs must be passe
31080 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 d as the xStep a
31090 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 nd xFinal.** par
310a0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 ameters. ^An agg
310b0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
310c0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
310d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
310e0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 f xStep.** and x
310f0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 Final and NULL p
31100 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 ointer must be p
31110 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e assed for xFunc.
31120 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 ^To delete an e
31130 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 xisting.** SQL f
31140 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
31150 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 gate, pass NULL
31160 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c pointers for all
31170 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a three function.
31180 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a ** callbacks..**
31190 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e .** ^(If the nin
311a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
311b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
311c0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 unction_v2() is
311d0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 not NULL,.** the
311e0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 n it is destruct
311f0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
31200 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
31210 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 ter. .** The des
31220 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b tructor is invok
31230 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 ed when the func
31240 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c tion is deleted,
31250 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 either by being
31260 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f .** overloaded o
31270 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 r when the datab
31280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
31290 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 loses.)^.** ^The
312a0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 destructor is a
312b0 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 lso invoked if t
312c0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 he call to.** sq
312d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
312e0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 ction_v2() fails
312f0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 ..** ^When the d
31300 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 estructor callba
31310 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 ck of the tenth
31320 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 parameter is inv
31330 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 oked, it.** is p
31340 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 assed a single a
31350 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
31360 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 a copy of the a
31370 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
31380 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 .** pointer whic
31390 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 h was the fifth
313a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
313b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
313c0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a tion_v2()..**.**
313d0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 ^It is permitte
313e0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 d to register mu
313f0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
31400 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
31410 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 me.** functions
31420 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
31430 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 me but with eith
31440 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d er differing num
31450 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d bers of.** argum
31460 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e ents or differin
31470 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 g preferred text
31480 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 encodings. ^SQ
31490 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a Lite will use.**
314a0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
314b0 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c ion that most cl
314c0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
314d0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
314e0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
314f0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 on is used. ^A
31500 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
31510 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e ntation with a n
31520 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e on-negative.** n
31530 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 Arg parameter is
31540 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 a better match
31550 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
31560 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
31570 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 ith.** a negativ
31580 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 e nArg. ^A func
31590 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 tion where the p
315a0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
315b0 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 coding.** matche
315c0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 s the database e
315d0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 ncoding is a bet
315e0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 ter.** match tha
315f0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
31600 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
31610 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a is different. .
31620 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 ** ^A function w
31630 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
31640 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
31650 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
31660 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
31670 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
31680 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
31690 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
316a0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
316b0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
316c0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
316d0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e ** ^Built-in fun
316e0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 ctions may be ov
316f0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 erloaded by new
31700 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
31710 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ned functions..*
31720 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 *.** ^An applica
31730 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
31740 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
31750 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
31760 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
31770 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
31780 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
31790 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
317a0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
317b0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
317c0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
317d0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
317e0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
317f0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
31800 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 unning..*/.int s
31810 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
31820 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
31830 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
31840 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
31850 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
31860 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
31870 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
31880 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
31890 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
318a0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
318b0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
318c0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
318d0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
318e0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
318f0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
31900 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
31910 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
31920 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
31930 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
31940 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
31950 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
31960 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
31970 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
31980 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
31990 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
319a0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
319b0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
319c0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
319d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
319e0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
319f0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
31a00 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
31a10 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 ntext*).);.int s
31a20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
31a30 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c nction_v2(. sql
31a40 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
31a50 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
31a60 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
31a70 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
31a80 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
31a90 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
31aa0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
31ab0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
31ac0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
31ad0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
31ae0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
31af0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
31b00 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
31b10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
31b20 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
31b30 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a roy)(void*).);..
31b40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
31b50 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a Text Encodings.*
31b60 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
31b70 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ant define integ
31b80 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 er codes that re
31b90 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 present the vari
31ba0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f ous.** text enco
31bb0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 dings supported
31bc0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 by SQLite..*/.#d
31bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
31be0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 8 1.#d
31bf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
31c00 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 16LE 2.#d
31c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
31c20 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 16BE 3.#d
31c30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
31c40 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 16 4
31c50 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 /* Use native b
31c60 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 yte order */.#de
31c70 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 fine SQLITE_ANY
31c80 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 5
31c90 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f /* Deprecated */
31ca0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
31cb0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 UTF16_ALIGNED 8
31cc0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
31cd0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 reate_collation
31ce0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 only */../*.** C
31cf0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f API3REF: Functio
31d00 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 n Flags.**.** Th
31d10 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 ese constants ma
31d20 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 y be ORed togeth
31d30 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 er with the .**
31d40 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 [SQLITE_UTF8 | p
31d50 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
31d60 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 coding] as the f
31d70 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a ourth argument.*
31d80 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 * to [sqlite3_cr
31d90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
31da0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
31db0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c e_function16()],
31dc0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
31dd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
31de0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e v2()]..*/.#defin
31df0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 e SQLITE_DETERMI
31e00 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a NISTIC 0x800.
31e10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
31e20 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 Deprecated Func
31e30 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 tions.** DEPRECA
31e40 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 TED.**.** These
31e50 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 functions are [d
31e60 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 eprecated]. In
31e70 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 order to maintai
31e80 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 n.** backwards c
31e90 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 ompatibility wit
31ea0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 h older code, th
31eb0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f ese functions co
31ec0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 ntinue .** to be
31ed0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 supported. How
31ee0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 ever, new applic
31ef0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 ations should av
31f00 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f oid.** the use o
31f10 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e f these function
31f20 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f s. To help enco
31f30 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 urage people to
31f40 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 avoid.** using t
31f50 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 hese functions,
31f60 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 we are not going
31f70 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 to tell you wha
31f80 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 t they do..*/.#i
31f90 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
31fa0 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c T_DEPRECATED.SQL
31fb0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
31fc0 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 nt sqlite3_aggre
31fd0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 gate_count(sqlit
31fe0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 e3_context*);.SQ
31ff0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
32000 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 int sqlite3_expi
32010 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
32020 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 *);.SQLITE_DEPRE
32030 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 CATED int sqlite
32040 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 3_transfer_bindi
32050 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ngs(sqlite3_stmt
32060 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a *, sqlite3_stmt*
32070 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 );.SQLITE_DEPREC
32080 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
32090 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 _global_recover(
320a0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 void);.SQLITE_DE
320b0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 PRECATED void sq
320c0 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 lite3_thread_cle
320d0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 anup(void);.SQLI
320e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
320f0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 t sqlite3_memory
32100 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
32110 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
32120 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 64,int),.
32130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
32140 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
32150 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
32160 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
32170 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
32180 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
32190 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 lues.**.** The C
321a0 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d -language implem
321b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 entation of SQL
321c0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 functions and ag
321d0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a gregates uses.**
321e0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 this set of int
321f0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 erface routines
32200 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 to access the pa
32210 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f rameter values o
32220 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f n.** the functio
32230 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a n or aggregate..
32240 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 **.** The xFunc
32250 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 (for scalar func
32260 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 tions) or xStep
32270 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 (for aggregates)
32280 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 parameters.** t
32290 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
322a0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e e_function()] an
322b0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 d [sqlite3_creat
322c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a e_function16()].
322d0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 ** define callba
322e0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 cks that impleme
322f0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
32300 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 ions and aggrega
32310 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 tes..** The 3rd
32320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
32330 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 se callbacks is
32340 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
32350 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 ters to.** [prot
32360 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
32370 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 lue] objects. T
32380 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c here is one [sql
32390 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
323a0 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 ct for.** each p
323b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
323c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 SQL function. T
323d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
323e0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 e used to.** ext
323f0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d ract values from
32400 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
32410 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
32420 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
32430 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 es work only wit
32440 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c h [protected sql
32450 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
32460 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 cts..** Any atte
32470 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 mpt to use these
32480 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 routines on an
32490 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
324a0 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f ite3_value].** o
324b0 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e bject results in
324c0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
324d0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 ior..**.** ^Thes
324e0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 e routines work
324f0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f just like the co
32500 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c rresponding [col
32510 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
32520 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 ions].** except
32530 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 that these rout
32540 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 ines take a sing
32550 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 le [protected sq
32560 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
32570 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ect.** pointer i
32580 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c nstead of a [sql
32590 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e ite3_stmt*] poin
325a0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 ter and an integ
325b0 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 er column number
325c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
325d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
325e0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
325f0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
32600 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
32610 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
32620 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
32630 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a achine. ^The.**
32640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
32650 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
32660 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32670 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
32680 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
32690 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
326a0 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
326b0 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
326c0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
326d0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^(The sqlite3_va
326e0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
326f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
32700 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
32710 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
32720 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
32730 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
32740 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
32750 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
32760 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
32770 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
32780 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
32790 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
327a0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
327b0 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
327c0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
327d0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
327e0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
327f0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
32800 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
32810 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
32820 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
32830 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
32840 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
32850 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
32860 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
32870 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
32880 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
32890 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a is returned.)^.*
328a0 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 *.** Please pay
328b0 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e particular atten
328c0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 tion to the fact
328d0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 that the pointe
328e0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 r returned.** fr
328f0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
32900 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 e_blob()], [sqli
32910 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
32920 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
32930 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
32940 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 ] can be invalid
32950 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 ated by a subseq
32960 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 uent call to.**
32970 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
32980 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ytes()], [sqlite
32990 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
329a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
329b0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
329c0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
329d0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a _text16()]..**.*
329e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
329f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
32a00 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
32a10 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 read as.** the S
32a20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 QL function that
32a30 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 supplied the [s
32a40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 qlite3_value*] p
32a50 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f arameters..*/.co
32a60 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
32a70 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 3_value_blob(sql
32a80 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
32a90 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
32aa0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 bytes(sqlite3_va
32ab0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
32ac0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 e3_value_bytes16
32ad0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
32ae0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 ;.double sqlite3
32af0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 _value_double(sq
32b00 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
32b10 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
32b20 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c _int(sqlite3_val
32b30 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e ue*);.sqlite3_in
32b40 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64 sqlite3_valu
32b50 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f e_int64(sqlite3_
32b60 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 value*);.const u
32b70 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 nsigned char *sq
32b80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32b90 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
32ba0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 ;.const void *sq
32bb0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
32bc0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
32bd0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a *);.const void *
32be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
32bf0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 xt16le(sqlite3_v
32c00 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f alue*);.const vo
32c10 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 id *sqlite3_valu
32c20 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 e_text16be(sqlit
32c30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
32c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
32c50 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
32c60 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
32c70 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
32c80 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
32c90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
32ca0 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 REF: Obtain Aggr
32cb0 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 egate Function C
32cc0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 ontext.**.** Imp
32cd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
32ce0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
32cf0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 nctions use this
32d00 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 .** routine to a
32d10 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 llocate memory f
32d20 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
32d30 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 state..**.** ^T
32d40 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
32d50 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
32d60 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
32d70 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
32d80 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 ed .** for a par
32d90 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 ticular aggregat
32da0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 e function, SQLi
32db0 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 te.** allocates
32dc0 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 N of memory, zer
32dd0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d oes out that mem
32de0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 ory, and returns
32df0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
32e00 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e the new memory.
32e10 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 ^On second and
32e20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
32e30 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 to.** sqlite3_a
32e40 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
32e50 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 () for the same
32e60 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
32e70 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 on instance,.**
32e80 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 the same buffer
32e90 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 is returned. Sq
32ea0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
32eb0 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 context() is nor
32ec0 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 mally.** called
32ed0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e once for each in
32ee0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 vocation of the
32ef0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 xStep callback a
32f00 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c nd then one.** l
32f10 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 ast time when th
32f20 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
32f30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e k is invoked. ^
32f40 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 (When no rows ma
32f50 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 tch.** an aggreg
32f60 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 ate query, the x
32f70 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 Step() callback
32f80 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 of the aggregate
32f90 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 function.** imp
32fa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
32fb0 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 ever called and
32fc0 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c xFinal() is call
32fd0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e ed exactly once.
32fe0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 .** In those cas
32ff0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 es, sqlite3_aggr
33000 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
33010 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 might be called
33020 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 for the.** first
33030 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 time from withi
33040 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a n xFinal().)^.**
33050 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
33060 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
33070 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
33080 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
33090 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 ointer .** when
330a0 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 first called if
330b0 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f N is less than o
330c0 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 r equal to zero
330d0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a or if a memory.*
330e0 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 * allocate error
330f0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e occurs..**.** ^
33100 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 (The amount of s
33110 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 pace allocated b
33120 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 y sqlite3_aggreg
33130 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
33140 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 is.** determine
33150 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d d by the N param
33160 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 eter on first su
33170 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 ccessful call.
33180 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 Changing the.**
33190 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 value of N in su
331a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
331b0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
331c0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 te_context() wit
331d0 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 hin.** the same
331e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
331f0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c on instance will
33200 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 not resize the
33210 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
33220 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 tion.)^ Within
33230 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 the xFinal callb
33240 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f ack, it is custo
33250 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e mary to set.** N
33260 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 =0 in calls to s
33270 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
33280 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f _context(C,N) so
33290 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 that no .** poi
332a0 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c ntless memory al
332b0 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e locations occur.
332c0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 .**.** ^SQLite a
332d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
332e0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
332f0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 located by .** s
33300 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
33310 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 _context() when
33320 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 the aggregate qu
33330 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a ery concludes..*
33340 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
33350 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 arameter must be
33360 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
33370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 * [sqlite3_conte
33380 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f xt | SQL functio
33390 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 n context] that
333a0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
333b0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
333c0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c xStep or xFinal
333d0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e callback routin
333e0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 e that implement
333f0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a s the aggregate.
33400 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ** function..**.
33410 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
33420 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
33430 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
33440 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
33450 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
33460 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
33470 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a nning..*/.void *
33480 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
33490 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 e_context(sqlite
334a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 3_context*, int
334b0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 nBytes);../*.**
334c0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 CAPI3REF: User D
334d0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e ata For Function
334e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
334f0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
33500 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
33510 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
33520 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 the pointer that
33530 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 was the pUserDa
33540 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 ta parameter (th
33550 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 e 5th parameter)
33560 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
33570 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
33580 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
33590 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
335a0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
335b0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
335c0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
335d0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
335e0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
335f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
33600 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
33610 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
33620 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
33630 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c hich.** the appl
33640 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
33650 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
33660 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
33670 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
33680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33690 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
336a0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
336b0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 nection For Func
336c0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tions.**.** ^The
336d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
336e0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 _db_handle() int
336f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
33700 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
33710 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
33720 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
33730 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 ion] (the 1st pa
33740 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 rameter).** of t
33750 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 he [sqlite3_crea
33760 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a te_function()].*
33770 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 * and [sqlite3_c
33780 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
33790 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 ()] routines tha
337a0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 t originally.**
337b0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 registered the a
337c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
337d0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a ed function..*/.
337e0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 sqlite3 *sqlite3
337f0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
33800 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
33810 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
33820 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 I3REF: Function
33830 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a Auxiliary Data.*
33840 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 *.** These funct
33850 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 ions may be used
33860 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 by (non-aggrega
33870 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e te) SQL function
33880 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 s to.** associat
33890 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 e metadata with
338a0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e argument values.
338b0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c If the same val
338c0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a ue is passed to.
338d0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f ** multiple invo
338e0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 cations of the s
338f0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ame SQL function
33900 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 during query ex
33910 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a ecution, under.*
33920 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 * some circumsta
33930 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 nces the associa
33940 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 ted metadata may
33950 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 be preserved.
33960 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 An example.** of
33970 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 where this migh
33980 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 t be useful is i
33990 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 n a regular-expr
339a0 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a ession matching.
339b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 ** function. The
339c0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f compiled versio
339d0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 n of the regular
339e0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 expression can
339f0 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 be stored as.**
33a00 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 metadata associa
33a10 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74 ted with the pat
33a20 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a tern string. .*
33a30 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 * Then as long a
33a40 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 s the pattern st
33a50 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 ring remains the
33a60 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f same,.** the co
33a70 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 mpiled regular e
33a80 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 xpression can be
33a90 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 reused on multi
33aa0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ple.** invocatio
33ab0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 ns of the same f
33ac0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e unction..**.** ^
33ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
33ae0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
33af0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
33b00 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 inter to the met
33b10 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 adata.** associa
33b20 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
33b30 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
33b40 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 function with t
33b50 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a he Nth argument.
33b60 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 ** value to the
33b70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33b80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 ned function. ^I
33b90 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 f there is no me
33ba0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
33bb0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75 ated with the fu
33bc0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c nction argument,
33bd0 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 this sqlite3_ge
33be0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
33bf0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 rface.** returns
33c00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
33c10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
33c20 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
33c30 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 C,N,P,X) interfa
33c40 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 ce saves P as me
33c50 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e tadata for the N
33c60 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 -th.** argument
33c70 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
33c80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33c90 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e ion. ^Subsequen
33ca0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 t.** calls to sq
33cb0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
33cc0 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 a(C,N) return P
33cd0 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 from the most re
33ce0 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cent.** sqlite3_
33cf0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
33d00 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 P,X) call if the
33d10 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69 metadata is sti
33d20 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e ll valid or.** N
33d30 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 ULL if the metad
33d40 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 ata has been dis
33d50 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 carded..** ^Afte
33d60 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 r each call to s
33d70 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
33d80 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 ta(C,N,P,X) wher
33d90 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c e X is not NULL,
33da0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
33db0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 invoke the destr
33dc0 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 uctor function X
33dd0 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 with parameter
33de0 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 P exactly.** onc
33df0 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 e, when the meta
33e00 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65 data is discarde
33e10 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 d..** SQLite is
33e20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 free to discard
33e30 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 the metadata at
33e40 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 any time, includ
33e50 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 ing: <ul>.** <li
33e60 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 > when the corre
33e70 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f sponding functio
33e80 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e n parameter chan
33e90 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ges, or.** <li>
33ea0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 when [sqlite3_re
33eb0 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
33ec0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 e3_finalize()] i
33ed0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 s called for the
33ee0 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 .** SQL sta
33ef0 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c tement, or.** <l
33f00 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f i> when sqlite3_
33f10 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 set_auxdata() is
33f20 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f invoked again o
33f30 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d n the same param
33f40 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e eter, or.** <li>
33f50 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 during the orig
33f60 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 inal sqlite3_set
33f70 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 _auxdata() call
33f80 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a when a memory .*
33f90 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f * allocatio
33fa0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
33fb0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f </ul>)^.**.** No
33fc0 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c te the last bull
33fd0 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 et in particular
33fe0 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f . The destructo
33ff0 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 r X in .** sqlit
34000 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
34010 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 ,N,P,X) might be
34020 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 called immediat
34030 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a ely, before the.
34040 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 ** sqlite3_set_a
34050 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
34060 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e ce even returns.
34070 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f Hence sqlite3_
34080 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a set_auxdata().**
34090 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 should be calle
340a0 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f d near the end o
340b0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 f the function i
340c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e mplementation an
340d0 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f d the.** functio
340e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
340f0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 should not make
34100 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 any use of P af
34110 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 ter.** sqlite3_s
34120 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 et_auxdata() has
34130 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a been called..**
34140 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 .** ^(In practic
34150 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 e, metadata is p
34160 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e reserved between
34170 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 function calls
34180 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 for.** function
34190 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 parameters that
341a0 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 are compile-time
341b0 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c constants, incl
341c0 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a uding literal.**
341d0 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 values and [par
341e0 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 ameters] and exp
341f0 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 ressions compose
34200 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e d from the same.
34210 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 )^.**.** These r
34220 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 outines must be
34230 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
34240 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
34250 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 hich.** the SQL
34260 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
34270 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 ing..*/.void *sq
34280 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
34290 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
342a0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 t*, int N);.void
342b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
342c0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
342d0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f text*, int N, vo
342e0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f id*, void (*)(vo
342f0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 id*));.../*.** C
34300 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e API3REF: Constan
34310 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 ts Defining Spec
34320 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 ial Destructor B
34330 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 ehavior.**.** Th
34340 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 ese are special
34350 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 values for the d
34360 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 estructor that i
34370 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 s passed in as t
34380 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 he.** final argu
34390 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 ment to routines
343a0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 like [sqlite3_r
343b0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 esult_blob()].
343c0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74 ^If the destruct
343d0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 or.** argument i
343e0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c s SQLITE_STATIC,
343f0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
34400 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 he content point
34410 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a er is constant.*
34420 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 * and will never
34430 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 change. It doe
34440 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 s not need to be
34450 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 destroyed. ^Th
34460 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e e.** SQLITE_TRAN
34470 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e SIENT value mean
34480 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 s that the conte
34490 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 nt will likely c
344a0 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 hange in.** the
344b0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 near future and
344c0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 that SQLite shou
344d0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 ld make its own
344e0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a private copy of.
344f0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 ** the content b
34500 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
34510 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 .**.** The typed
34520 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 ef is necessary
34530 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 to work around p
34540 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 roblems in certa
34550 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c in.** C++ compil
34560 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ers..*/.typedef
34570 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 void (*sqlite3_d
34580 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 estructor_type)(
34590 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 void*);.#define
345a0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 SQLITE_STATIC
345b0 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 ((sqlite3_des
345c0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a tructor_type)0).
345d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
345e0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c RANSIENT ((sql
345f0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f ite3_destructor_
34600 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 type)-1)../*.**
34610 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e CAPI3REF: Settin
34620 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 g The Result Of
34630 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a An SQL Function.
34640 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
34650 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 ines are used by
34660 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 the xFunc or xF
34670 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 inal callbacks t
34680 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 hat.** implement
34690 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
346a0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 nd aggregates.
346b0 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f See.** [sqlite3_
346c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
346d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
346e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
346f0 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 6()].** for addi
34700 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
34710 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on..**.** These
34720 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 functions work v
34730 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 ery much like th
34740 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e e [parameter bin
34750 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a ding] family of.
34760 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 ** functions use
34770 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 d to bind values
34780 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 to host paramet
34790 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 ers in prepared
347a0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 statements..** R
347b0 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c efer to the [SQL
347c0 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 parameter] docu
347d0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 mentation for ad
347e0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
347f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
34800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34810 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 blob() interface
34820 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 sets the result
34830 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c from.** an appl
34840 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
34850 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 function to be t
34860 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f he BLOB whose co
34870 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 ntent is pointed
34880 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 .** to by the se
34890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 cond parameter a
348a0 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 nd which is N by
348b0 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e tes long where N
348c0 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 is the.** third
348d0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
348e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
348f0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 esult_zeroblob()
34900 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 interfaces set
34910 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
34920 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
34930 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
34940 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 n to be a BLOB c
34950 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 ontaining all ze
34960 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 ro.** bytes and
34970 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c N bytes in size,
34980 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 where N is the
34990 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 value of the 2nd
349a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
349b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
349c0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 esult_double() i
349d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
349e0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a e result from.**
349f0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d an application-
34a00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34a10 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e to be a floatin
34a20 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 g point value sp
34a30 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 ecified.** by it
34a40 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a s 2nd argument..
34a50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
34a60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
34a70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
34a80 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 sult_error16() f
34a90 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 unctions.** caus
34aa0 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 e the implemente
34ab0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 d SQL function t
34ac0 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 o throw an excep
34ad0 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 tion..** ^SQLite
34ae0 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 uses the string
34af0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
34b00 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 he.** 2nd parame
34b10 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 ter of sqlite3_r
34b20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 esult_error() or
34b30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34b40 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 error16().** as
34b50 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 the text of an e
34b60 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e rror message. ^
34b70 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 SQLite interpret
34b80 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
34b90 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 essage string fr
34ba0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
34bb0 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 t_error() as UTF
34bc0 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 -8. ^SQLite.** i
34bd0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74 nterprets the st
34be0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
34bf0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
34c00 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 () as UTF-16 in
34c10 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f native.** byte o
34c20 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 rder. ^If the t
34c30 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
34c40 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
34c50 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 _error().** or s
34c60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
34c70 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 ror16() is negat
34c80 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 ive then SQLite
34c90 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 takes as the err
34ca0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c or.** message al
34cb0 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 l text up throug
34cc0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
34cd0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
34ce0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
34cf0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
34d00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
34d10 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 or.** sqlite3_r
34d20 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
34d30 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 is non-negative
34d40 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
34d50 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 s that many.** b
34d60 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 ytes (not charac
34d70 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 ters) from the 2
34d80 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 nd parameter as
34d90 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
34da0 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 e..** ^The sqlit
34db0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
34dc0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
34dd0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a sult_error16().*
34de0 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 * routines make
34df0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f a private copy o
34e00 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 f the error mess
34e10 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a age text before.
34e20 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 ** they return.
34e30 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c Hence, the call
34e40 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e ing function can
34e50 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a deallocate or.*
34e60 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 * modify the tex
34e70 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 t after they ret
34e80 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d urn without harm
34e90 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
34ea0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
34eb0 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 ode() function c
34ec0 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 hanges the error
34ed0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 code.** returne
34ee0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 d by SQLite as a
34ef0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 result of an er
34f00 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f ror in a functio
34f10 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c n. ^By default,
34f20 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f .** the error co
34f30 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 de is SQLITE_ERR
34f40 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 OR. ^A subseque
34f50 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 nt call to sqlit
34f60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
34f70 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
34f80 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
34f90 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f resets the erro
34fa0 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 r code to SQLITE
34fb0 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 _ERROR..**.** ^T
34fc0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
34fd0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 t_error_toobig()
34fe0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
34ff0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
35000 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e w an.** error in
35010 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
35020 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 string or BLOB i
35030 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 s too long to re
35040 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e present..**.** ^
35050 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
35060 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 lt_error_nomem()
35070 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 interface cause
35080 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f s SQLite to thro
35090 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e w an.** error in
350a0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 dicating that a
350b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
350c0 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 n failed..**.**
350d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
350e0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 ult_int() interf
350f0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 ace sets the ret
35100 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 urn value.** of
35110 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
35120 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35130 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 to be the 32-bi
35140 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
35150 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 .** value given
35160 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d in the 2nd argum
35170 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ent..** ^The sql
35180 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
35190 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 4() interface se
351a0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ts the return va
351b0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 lue.** of the ap
351c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
351d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
351e0 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e the 64-bit sign
351f0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 ed integer.** va
35200 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 lue given in the
35210 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2nd argument..*
35220 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35230 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 3_result_null()
35240 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
35250 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
35260 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
35270 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
35280 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c nction to be NUL
35290 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 L..**.** ^The sq
352a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
352b0 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 t(), sqlite3_res
352c0 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a ult_text16(),.**
352d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
352e0 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 text16le(), and
352f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35300 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 ext16be() interf
35310 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 aces.** set the
35320 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
35330 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
35340 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35350 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 to be.** a text
35360 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
35370 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 represented as
35380 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 UTF-8, UTF-16 na
35390 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c tive byte order,
353a0 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c .** UTF-16 littl
353b0 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 e endian, or UTF
353c0 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 -16 big endian,
353d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
353e0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 ^SQLite takes t
353f0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 he text result f
35400 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 rom the applicat
35410 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ion from.** the
35420 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
35430 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
35440 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
35450 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 aces..** ^If the
35460 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
35470 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
35480 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
35490 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 faces.** is nega
354a0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 tive, then SQLit
354b0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 e takes result t
354c0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 ext from the 2nd
354d0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 parameter.** th
354e0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
354f0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
35500 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 ** ^If the 3rd p
35510 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
35520 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35530 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
35540 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 ** is non-negati
35550 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 ve, then as many
35560 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
35570 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 acters) of the t
35580 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ext.** pointed t
35590 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 o by the 2nd par
355a0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e ameter are taken
355b0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 as the applicat
355c0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 ion-defined.** f
355d0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 unction result.
355e0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
355f0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 meter is non-neg
35600 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a ative, then it.*
35610 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 * must be the by
35620 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 te offset into t
35630 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 he string where
35640 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 the NUL terminat
35650 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 or would.** appe
35660 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ar if the string
35670 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 where NUL termi
35680 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
35690 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
356a0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 cur.** in the st
356b0 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f ring at a byte o
356c0 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 ffset that is le
356d0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 ss than the valu
356e0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 e of the 3rd.**
356f0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
35700 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
35710 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 ring will contai
35720 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 n embedded NULs
35730 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c and the.** resul
35740 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
35750 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 operating on st
35760 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 rings with embed
35770 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
35780 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 fined..** ^If th
35790 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
357a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
357b0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
357c0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
357d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
357e0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
357f0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
35800 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
35810 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
35820 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
35830 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
35840 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
35850 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
35860 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
35870 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
35880 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
35890 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
358a0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
358b0 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 es or to.** sqli
358c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
358d0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
358e0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
358f0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
35900 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
35910 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
35920 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
35930 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
35940 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
35950 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 copy the content
35960 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 of the paramete
35970 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 r nor call a des
35980 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 tructor on the c
35990 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 ontent.** when i
359a0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 t has finished u
359b0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
359c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
359d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
359e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
359f0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
35a00 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
35a10 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
35a20 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
35a30 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ant SQLITE_TRANS
35a40 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c IENT.** then SQL
35a50 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
35a60 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 of the result i
35a70 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e nto space obtain
35a80 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 ed from.** from
35a90 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
35aa0 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 )] before it ret
35ab0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
35ac0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
35ad0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
35ae0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
35af0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
35b00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
35b10 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
35b20 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
35b30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
35b40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
35b50 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
35b60 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
35b70 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
35b80 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
35b90 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
35ba0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
35bb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
35bc0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
35bd0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
35be0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
35bf0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
35c00 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
35c10 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
35c20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
35c30 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
35c40 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 hout harm..** ^A
35c50 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
35c60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
35c70 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
35c80 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
35c90 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
35ca0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
35cb0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
35cc0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
35cd0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
35ce0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
35cf0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
35d00 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
35d10 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
35d20 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
35d30 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
35d40 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
35d50 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
35d60 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
35d70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35d80 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
35d90 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
35da0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
35db0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
35dc0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
35dd0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 defined..*/.void
35de0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
35df0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e blob(sqlite3_con
35e00 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 text*, const voi
35e10 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
35e20 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
35e30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f qlite3_result_do
35e40 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e uble(sqlite3_con
35e50 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a text*, double);.
35e60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
35e70 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 ult_error(sqlite
35e80 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
35e90 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 t char*, int);.v
35ea0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
35eb0 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 lt_error16(sqlit
35ec0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
35ed0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a st void*, int);.
35ee0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
35ef0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 ult_error_toobig
35f00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
35f10 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
35f20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f _result_error_no
35f30 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 mem(sqlite3_cont
35f40 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 ext*);.void sqli
35f50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
35f60 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f _code(sqlite3_co
35f70 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
35f80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
35f90 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f t_int(sqlite3_co
35fa0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f ntext*, int);.vo
35fb0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
35fc0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f t_int64(sqlite3_
35fd0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 context*, sqlite
35fe0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 3_int64);.void s
35ff0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 qlite3_result_nu
36000 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ll(sqlite3_conte
36010 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 xt*);.void sqlit
36020 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
36030 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
36040 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
36050 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
36060 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
36070 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
36080 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
36090 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
360a0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
360b0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
360c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 _result_text16le
360d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
360e0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
360f0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
36100 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 *));.void sqlite
36110 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 3_result_text16b
36120 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
36130 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c t*, const void*,
36140 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 int,void(*)(voi
36150 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 d*));.void sqlit
36160 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
36170 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
36180 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a , sqlite3_value*
36190 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
361a0 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 result_zeroblob(
361b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
361c0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a , int n);../*.**
361d0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e CAPI3REF: Defin
361e0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 e New Collating
361f0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 Sequences.**.**
36200 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
36210 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 add, remove, or
36220 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 modify a [colla
36230 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 tion] associated
36240 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 .** with the [da
36250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
36260 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20 n] specified as
36270 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
36280 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e nt..**.** ^The n
36290 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 ame of the colla
362a0 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 tion is a UTF-8
362b0 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 string.** for sq
362c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
362d0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c lation() and sql
362e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
362f0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e ation_v2().** an
36300 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e d a UTF-16 strin
36310 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
36320 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
36330 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
36340 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c ion16()..** ^Col
36350 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 lation names tha
36360 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 t compare equal
36370 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 according to [sq
36380 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 lite3_strnicmp()
36390 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 ] are.** conside
363a0 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 red to be the sa
363b0 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e me name..**.** ^
363c0 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d (The third argum
363d0 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d ent (eTextRep) m
363e0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 ust be one of th
363f0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 e constants:.**
36400 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
36410 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c LITE_UTF8],.** <
36420 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
36430 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 6LE],.** <li> [S
36440 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a QLITE_UTF16BE],.
36450 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
36460 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c UTF16], or.** <l
36470 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 i> [SQLITE_UTF16
36480 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f _ALIGNED]..** </
36490 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 ul>)^.** ^The eT
364a0 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 extRep argument
364b0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 determines the e
364c0 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e ncoding of strin
364d0 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 gs passed.** to
364e0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
364f0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c nction callback,
36500 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e xCallback..** ^
36510 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 The [SQLITE_UTF1
36520 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 6] and [SQLITE_U
36530 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 TF16_ALIGNED] va
36540 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 lues for eTextRe
36550 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e p.** force strin
36560 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 gs to be UTF16 w
36570 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 ith native byte
36580 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b order..** ^The [
36590 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
365a0 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 GNED] value for
365b0 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 eTextRep forces
365c0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e strings to begin
365d0 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 .** on an even b
365e0 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a yte address..**.
365f0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 ** ^The fourth a
36600 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 rgument, pArg, i
36610 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e s an application
36620 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 data pointer th
36630 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 at is passed.**
36640 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 through as the f
36650 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
36660 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
36670 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b unction callback
36680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 ..**.** ^The fif
36690 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 th argument, xCa
366a0 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 llback, is a poi
366b0 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c nter to the coll
366c0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a ating function..
366d0 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c ** ^Multiple col
366e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 lating functions
366f0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 can be register
36700 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d ed using the sam
36710 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 e name but.** wi
36720 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 th different eTe
36730 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 xtRep parameters
36740 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c and SQLite will
36750 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a use whichever.*
36760 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 * function requi
36770 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d res the least am
36780 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 ount of data tra
36790 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 nsformation..**
367a0 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 ^If the xCallbac
367b0 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 k argument is NU
367c0 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c LL then the coll
367d0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 ating function i
367e0 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e s.** deleted. ^
367f0 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 When all collati
36800 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 ng functions hav
36810 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ing the same nam
36820 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a e are deleted,.*
36830 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e * that collation
36840 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 is no longer us
36850 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 able..**.** ^The
36860 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
36870 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ion callback is
36880 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 invoked with a c
36890 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 opy of the pArg
368a0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 .** application
368b0 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 data pointer and
368c0 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 with two string
368d0 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e s in the encodin
368e0 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 g specified.** b
368f0 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61 y the eTextRep a
36900 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f rgument. The co
36910 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
36920 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a must return an.
36930 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 ** integer that
36940 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 is negative, zer
36950 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a o, or positive.*
36960 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 * if the first s
36970 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 tring is less th
36980 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 an, equal to, or
36990 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 greater than th
369a0 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 e second,.** res
369b0 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f pectively. A co
369c0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
369d0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 must always ret
369e0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 urn the same ans
369f0 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 wer.** given the
36a00 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 same inputs. I
36a10 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f f two or more co
36a20 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
36a30 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64 s are registered
36a40 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 .** to the same
36a50 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 collation name (
36a60 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 using different
36a70 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 eTextRep values)
36a80 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 then all.** mus
36a90 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 t give an equiva
36aa0 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e lent answer when
36ab0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 invoked with eq
36ac0 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 uivalent strings
36ad0 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 ..** The collati
36ae0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ng function must
36af0 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 obey the follow
36b00 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 ing properties f
36b10 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 or all.** string
36b20 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a s A, B, and C:.*
36b30 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
36b40 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 > If A==B then B
36b50 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 ==A..** <li> If
36b60 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 A==B and B==C th
36b70 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e en A==C..** <li>
36b80 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 If A<B THEN
36b90 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 B>A..** <li>
36ba0 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 If A<B and B&
36bb0 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 lt;C then A<C
36bc0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a ..** </ol>.**.**
36bd0 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 If a collating
36be0 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 function fails a
36bf0 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 ny of the above
36c00 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 constraints and
36c10 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e that.** collatin
36c20 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 g function is r
36c30 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 egistered and us
36c40 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 ed, then the beh
36c50 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a avior of SQLite.
36c60 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
36c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36c80 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
36c90 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 tion_v2() works
36ca0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 like sqlite3_cre
36cb0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a ate_collation().
36cc0 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69 ** with the addi
36cd0 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 tion that the xD
36ce0 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 estroy callback
36cf0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 is invoked on pA
36d00 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 rg when.** the c
36d10 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
36d20 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a n is deleted..**
36d30 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 ^Collating func
36d40 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 tions are delete
36d50 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 d when they are
36d60 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 overridden by la
36d70 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ter.** calls to
36d80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 the collation cr
36d90 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 eation functions
36da0 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 or when the.**
36db0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
36dc0 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 tion] is closed
36dd0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 using [sqlite3_c
36de0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e lose()]..**.** ^
36df0 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c The xDestroy cal
36e00 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c lback is <u>not<
36e10 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 /u> called if th
36e20 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 e .** sqlite3_cr
36e30 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
36e40 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 2() function fai
36e50 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ls. Application
36e60 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a s that invoke.**
36e70 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
36e80 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 collation_v2() w
36e90 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 ith a non-NULL x
36ea0 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 Destroy argument
36eb0 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 should .** chec
36ec0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
36ed0 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 e and dispose of
36ee0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36ef0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a data pointer.**
36f00 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 themselves rath
36f10 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e er than expectin
36f20 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c g SQLite to deal
36f30 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 with it for the
36f40 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 m..** This is di
36f50 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 fferent from eve
36f60 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ry other SQLite
36f70 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
36f80 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a inconsistency .*
36f90 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 * is unfortunate
36fa0 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 but cannot be c
36fb0 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 hanged without b
36fc0 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 reaking backward
36fd0 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c s .** compatibil
36fe0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ity..**.** See a
36ff0 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 lso: [sqlite3_c
37000 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
37010 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
37020 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
37030 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 16()]..*/.int sq
37040 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
37050 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 lation(. sqlite
37060 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 3*, . const cha
37070 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 r *zName, . int
37080 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
37090 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 id *pArg,. int(
370a0 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
370b0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
370c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
370d0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ).);.int sqlite3
370e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
370f0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a n_v2(. sqlite3*
37100 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 , . const char
37110 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 *zName, . int e
37120 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 TextRep, . void
37130 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 *pArg,. int(*x
37140 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 Compare)(void*,i
37150 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 nt,const void*,i
37160 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c nt,const void*),
37170 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f . void(*xDestro
37180 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 y)(void*).);.int
37190 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
371a0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 collation16(. s
371b0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
371c0 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 t void *zName,.
371d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a int eTextRep, .
371e0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 void *pArg,.
371f0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 int(*xCompare)(v
37200 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
37210 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 oid*,int,const v
37220 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid*).);../*.**
37230 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 CAPI3REF: Collat
37240 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 ion Needed Callb
37250 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 acks.**.** ^To a
37260 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 void having to r
37270 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c egister all coll
37280 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
37290 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 before a databas
372a0 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 e.** can be used
372b0 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 , a single callb
372c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 ack function may
372d0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 be registered w
372e0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 ith the.** [data
372f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37300 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
37310 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 henever an undef
37320 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a ined collation.*
37330 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 * sequence is re
37340 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 quired..**.** ^I
37350 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 f the function i
37360 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 s registered usi
37370 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 ng the sqlite3_c
37380 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
37390 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 ) API,.** then i
373a0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 t is passed the
373b0 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e names of undefin
373c0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 ed collation seq
373d0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 uences as string
373e0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 s.** encoded in
373f0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 UTF-8. ^If sqlit
37400 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 e3_collation_nee
37410 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c ded16() is used,
37420 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 .** the names ar
37430 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d e passed as UTF-
37440 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 16 in machine na
37450 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e tive byte order.
37460 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 .** ^A call to e
37470 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 ither function r
37480 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 eplaces the exis
37490 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e ting collation-n
374a0 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a eeded callback..
374b0 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 **.** ^(When the
374c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
374d0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 oked, the first
374e0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
374f0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 is a copy.** of
37500 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
37510 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
37520 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 ollation_needed(
37530 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
37540 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
37550 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 16(). The secon
37560 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
37570 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
37580 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 nnection. The t
37590 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
375a0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f one of [SQLITE_
375b0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
375c0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b TF16BE],.** or [
375d0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
375e0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 indicating the
375f0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 most desirable f
37600 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 orm of the colla
37610 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 tion.** sequence
37620 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
37630 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 ed. The fourth
37640 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
37650 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 name of the.**
37660 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 required collati
37670 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a on sequence.)^.*
37680 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 *.** The callbac
37690 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c k function shoul
376a0 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 d register the d
376b0 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e esired collation
376c0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
376d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
376e0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ion()], [sqlite3
376f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
37700 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 n16()], or.** [s
37710 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
37720 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a llation_v2()]..*
37730 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f /.int sqlite3_co
37740 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a llation_needed(.
37750 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
37760 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 oid*, . void(*)
37770 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c (void*,sqlite3*,
37780 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e int eTextRep,con
37790 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 st char*).);.int
377a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
377b0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 on_needed16(. s
377c0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 qlite3*, . void
377d0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 *,. void(*)(voi
377e0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 d*,sqlite3*,int
377f0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 eTextRep,const v
37800 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 oid*).);..#ifdef
37810 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 SQLITE_HAS_CODE
37820 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 C./*.** Specify
37830 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 the key for an e
37840 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 ncrypted databas
37850 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 e. This routine
37860 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 should be.** ca
37870 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 lled right after
37880 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e sqlite3_open().
37890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
378a0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 to implement thi
378b0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 s API is not ava
378c0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 ilable in the pu
378d0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 blic release.**
378e0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e of SQLite..*/.in
378f0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 t sqlite3_key(.
37900 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
37910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37920 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
37930 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
37940 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
37950 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
37960 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 The key */.);.i
37970 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 nt sqlite3_key_v
37980 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
37990 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,
379a0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
379b0 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f to be rekeyed */
379c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
379d0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 DbName,
379e0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 /* Name of the
379f0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 database */. c
37a00 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c onst void *pKey,
37a10 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a int nKey /*
37a20 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a The key */.);..
37a30 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 /*.** Change the
37a40 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 key on an open
37a50 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 database. If th
37a60 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 e current databa
37a70 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 se is not.** enc
37a80 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 rypted, this rou
37a90 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 tine will encryp
37aa0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d t it. If pNew==
37ab0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 0 or nNew==0, th
37ac0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 e.** database is
37ad0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a decrypted..**.*
37ae0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
37af0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
37b00 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
37b10 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
37b20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
37b30 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c Lite..*/.int sql
37b40 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 ite3_rekey(. sq
37b50 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
37b60 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
37b70 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
37b80 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
37b90 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
37ba0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
37bb0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a e new key */.);.
37bc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 int sqlite3_reke
37bd0 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 y_v2(. sqlite3
37be0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
37bf0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
37c00 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 se to be rekeyed
37c10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
37c20 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 *zDbName,
37c30 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 /* Name of
37c40 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a the database */.
37c50 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b const void *pK
37c60 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 ey, int nKey
37c70 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 /* The new key
37c80 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 */.);../*.** Spe
37c90 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 cify the activat
37ca0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 ion key for a SE
37cb0 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c E database. Unl
37cc0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 ess .** activate
37cd0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 d, none of the S
37ce0 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c EE routines will
37cf0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 work..*/.void s
37d00 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f qlite3_activate_
37d10 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 see(. const cha
37d20 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 r *zPassPhrase
37d30 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 /* Activat
37d40 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b ion phrase */.);
37d50 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 .#endif..#ifdef
37d60 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 SQLITE_ENABLE_CE
37d70 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 ROD./*.** Specif
37d80 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e y the activation
37d90 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 key for a CEROD
37da0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 database. Unle
37db0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 ss .** activated
37dc0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 , none of the CE
37dd0 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c ROD routines wil
37de0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 l work..*/.void
37df0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
37e00 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 _cerod(. const
37e10 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
37e20 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
37e30 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
37e40 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a .);.#endif../*.*
37e50 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
37e60 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
37e70 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a r A Short Time.*
37e80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
37e90 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f _sleep() functio
37ea0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 n causes the cur
37eb0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 rent thread to s
37ec0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
37ed0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 .** for at least
37ee0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c a number of mil
37ef0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 liseconds specif
37f00 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d ied in its param
37f10 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 eter..**.** If t
37f20 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
37f30 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 tem does not sup
37f40 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 port sleep reque
37f50 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c sts with.** mill
37f60 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
37f70 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
37f80 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
37f90 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 ounded up to.**
37fa0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f the nearest seco
37fb0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f nd. The number o
37fc0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f f milliseconds o
37fd0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
37fe0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 .** requested fr
37ff0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 om the operating
38000 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 system is retur
38010 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ned..**.** ^SQLi
38020 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
38030 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 is interface by
38040 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 calling the xSle
38050 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f ep().** method o
38060 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
38070 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
38080 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 ct. If the xSle
38090 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f ep() method.** o
380a0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
380b0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 S is not impleme
380c0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 nted correctly,
380d0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 or not implement
380e0 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 ed at.** all, th
380f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
38100 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 of sqlite3_sleep
38110 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 () may deviate f
38120 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 rom the descript
38130 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 ion.** in the pr
38140 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
38150 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
38160 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 3_sleep(int);../
38170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
38180 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 ame Of The Folde
38190 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 r Holding Tempor
381a0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 ary Files.**.**
381b0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c ^(If this global
381c0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 variable is mad
381d0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 e to point to a
381e0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a string which is.
381f0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 ** the name of a
38200 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 folder (a.k.a.
38210 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e directory), then
38220 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 all temporary f
38230 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 iles.** created
38240 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 by SQLite when u
38250 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 sing a built-in
38260 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 [sqlite3_vfs | V
38270 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 FS].** will be p
38280 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 laced in that di
38290 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 rectory.)^ ^If
382a0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a this variable.**
382b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
382c0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
382d0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 performs a searc
382e0 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 h for an appropr
382f0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 iate.** temporar
38300 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 y file directory
38310 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ..**.** It is no
38320 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f t safe to read o
38330 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 r modify this va
38340 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 riable in more t
38350 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 han one.** threa
38360 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 d at a time. It
38370 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 is not safe to
38380 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 read or modify t
38390 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 his variable.**
383a0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 if a [database c
383b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
383c0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 ing used at the
383d0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 same time in a s
383e0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 eparate.** threa
383f0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 d..** It is inte
38400 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 nded that this v
38410 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f ariable be set o
38420 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f nce.** as part o
38430 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 f process initia
38440 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 lization and bef
38450 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 ore any SQLite i
38460 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 nterface.** rout
38470 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 ines have been c
38480 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 alled and that t
38490 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d his variable rem
384a0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a ain unchanged.**
384b0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a thereafter..**.
384c0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 ** ^The [temp_st
384d0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
384e0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 agma] may modify
384f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 this variable a
38500 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 nd cause.** it t
38510 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
38520 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
38530 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
38540 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c . ^Furthermore,
38550 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 .** the [temp_st
38560 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
38570 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 agma] always ass
38580 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 umes that any st
38590 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 ring.** that thi
385a0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 s variable point
385b0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 s to is held in
385c0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
385d0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 from .** [sqlite
385e0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 3_malloc] and th
385f0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 e pragma may att
38600 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 empt to free tha
38610 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e t memory.** usin
38620 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d g [sqlite3_free]
38630 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 ..** Hence, if t
38640 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 his variable is
38650 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c modified directl
38660 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f y, either it sho
38670 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e uld be.** made N
38680 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 ULL or made to p
38690 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f oint to memory o
386a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
386b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a lite3_malloc].**
386c0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 or else the use
386d0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 of the [temp_st
386e0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 ore_directory pr
386f0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 agma] should be
38700 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c avoided..**.** <
38710 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
38720 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a s Runtime users:
38730 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 </b> The tempor
38740 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 ary directory mu
38750 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 st be set.** pri
38760 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b 73 or to calling [s
38770 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72 20 qlite3_open] or
38780 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
38790 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 ]. Otherwise, v
387a0 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 arious.** featur
387b0 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 es that require
387c0 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f the use of tempo
387d0 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 rary files may f
387e0 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61 6e ail. Here is an
387f0 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20 68 .** example of h
38800 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75 73 ow to do this us
38810 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68 65 ing C++ with the
38820 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 Windows Runtime
38830 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
38840 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50 43 ote><pre>.** LPC
38850 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69 6e WSTR