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 41 42 4f 52 fine SQLITE_ABOR
5950: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 T_ROLLBACK
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 (SQLITE_ABOR
5970: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 T | (2<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5990: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 RAINT_CHECK
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
59b0: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a RAINT | (1<<8)).
59c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
59d0: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 ONSTRAINT_COMMIT
59e0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 HOOK (SQLITE_C
59f0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c ONSTRAINT | (2<<
5a00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5a10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f TE_CONSTRAINT_FO
5a20: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 REIGNKEY (SQLI
5a30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5a40: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
5a50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5a60: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 T_FUNCTION (
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5a80: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 T | (4<<8)).#def
5a90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5aa0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 RAINT_NOTNULL
5ab0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5ac0: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a RAINT | (5<<8)).
5ad0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5ae0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 ONSTRAINT_PRIMAR
5af0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 YKEY (SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c ONSTRAINT | (6<<
5b10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5b20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 TE_CONSTRAINT_TR
5b30: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 IGGER (SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
5b50: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
5b60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b70: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 T_UNIQUE (
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
5b90: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 T | (8<<8)).#def
5ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
5bb0: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 RAINT_VTAB
5bc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
5bd0: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a RAINT | (9<<8)).
5be0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5bf0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 ONSTRAINT_ROWID
5c00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c ONSTRAINT |(10<<
5c20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5c30: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5c40: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 R_WAL (SQLI
5c50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c TE_NOTICE | (1<<
5c60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5c70: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 TE_NOTICE_RECOVE
5c80: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 R_ROLLBACK (SQLI
5c90: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c TE_NOTICE | (2<<
5ca0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
5cb0: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 TE_WARNING_AUTOI
5cc0: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 NDEX (SQLI
5cd0: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c TE_WARNING | (1<
5ce0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 <8))../*.** CAPI
5cf0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 3REF: Flags For
5d00: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 File Open Operat
5d10: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
5d20: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 bit values are
5d30: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
5d40: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 in the.** 3rd p
5d50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
5d60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
5d70: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e ()] interface an
5d80: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 d.** in the 4th
5d90: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
5da0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
5db0: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a pen] method..*/.
5dc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5dd0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 PEN_READONLY
5de0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 0x00000001
5df0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5e00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5e10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5e20: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 PEN_READWRITE
5e30: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 0x00000002
5e40: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5e50: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5e60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5e70: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 PEN_CREATE
5e80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 0x00000004
5e90: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5ea0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5ec0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
5ed0: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 E 0x00000008
5ee0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5f00: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 PEN_EXCLUSIVE
5f10: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 0x00000010
5f20: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5f40: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 PEN_AUTOPROXY
5f50: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 0x00000020
5f60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
5f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5f80: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 PEN_URI
5f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 0x00000040
5fa0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
5fb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
5fc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
5fd0: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 PEN_MEMORY
5fe0: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 0x00000080
5ff0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
6000: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
6020: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 PEN_MAIN_DB
6030: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 0x00000100
6040: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
6060: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 PEN_TEMP_DB
6070: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 0x00000200
6080: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
6090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
60a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
60b0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 0x00000400
60c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
60d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
60e0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c PEN_MAIN_JOURNAL
60f0: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 0x00000800
6100: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
6110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
6120: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
6130: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 0x00001000
6140: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
6150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
6160: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 PEN_SUBJOURNAL
6170: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 0x00002000
6180: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
61a0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
61b0: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 AL 0x00004000
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
61d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
61e0: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 PEN_NOMUTEX
61f0: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 0x00008000
6200: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
6210: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
6220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
6230: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 PEN_FULLMUTEX
6240: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 0x00010000
6250: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
6260: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
6270: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
6280: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 PEN_SHAREDCACHE
6290: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 0x00020000
62a0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
62b0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
62c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
62d0: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 PEN_PRIVATECACHE
62e0: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 0x00040000
62f0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 /* Ok for sqlit
6300: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a e3_open_v2() */.
6310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
6320: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 PEN_WAL
6330: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 0x00080000
6340: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a /* VFS only */.
6350: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 ./* Reserved:
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6370: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 0x00F00000
6380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
6390: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 REF: Device Char
63a0: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a acteristics.**.*
63b0: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 * The xDeviceCha
63c0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 racteristics met
63d0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 hod of the [sqli
63e0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a te3_io_methods].
63f0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e ** object return
6400: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
6410: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f ch is a vector o
6420: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 f these.** bit v
6430: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 alues expressing
6440: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 I/O characteris
6450: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 tics of the mass
6460: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 storage.** devi
6470: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 ce that holds th
6480: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 e file that the
6490: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
64a0: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 ods].** refers t
64b0: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c o..**.** The SQL
64c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
64d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
64e0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 that all writes
64f0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 of.** any size a
6500: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
6510: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6520: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a MICnnn values.**
6530: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 mean that write
6540: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 s of blocks that
6550: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 are nnn bytes i
6560: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 n size and.** ar
6570: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
6580: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 address which is
6590: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 an integer mult
65a0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 iple of.** nnn a
65b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
65c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
65d0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d E_APPEND value m
65e0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 eans.** that whe
65f0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 n data is append
6600: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 ed to a file, th
6610: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 e data is append
6620: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e ed.** first then
6630: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
6640: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 file is extende
6650: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 d, never the oth
6660: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 er.** way around
6670: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
6680: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 CAP_SEQUENTIAL p
6690: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
66a0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f at.** informatio
66b0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 n is written to
66c0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 disk in the same
66d0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a order as calls.
66e0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 ** to xWrite().
66f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6700: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 P_POWERSAFE_OVER
6710: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d WRITE property m
6720: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 eans that.** aft
6730: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 er reboot follow
6740: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 ing a crash or p
6750: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f ower loss, the o
6760: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a nly bytes in a.*
6770: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 * file that were
6780: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 written at the
6790: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 application leve
67a0: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 l might have cha
67b0: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 nged.** and that
67c0: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c adjacent bytes,
67d0: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 even bytes with
67e0: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 in the same sect
67f0: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e or are.** guaran
6800: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 teed to be uncha
6810: 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 nged..*/.#define
6820: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6830: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 OMIC
6840: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 0x00000001.
6850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6860: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 OCAP_ATOMIC512
6870: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6880: 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 000002.#define S
6890: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
68a0: 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 IC1K
68b0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 0x00000004.#d
68c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
68d0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 AP_ATOMIC2K
68e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
68f0: 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 0008.#define SQL
6900: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6910: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
6920: 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 0x00000010.#def
6930: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6940: 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 _ATOMIC8K
6950: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6960: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
6970: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 E_IOCAP_ATOMIC16
6980: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 K 0
6990: 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e x00000040.#defin
69a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
69b0: 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 TOMIC32K
69c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
69d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
69e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 IOCAP_ATOMIC64K
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6a00: 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 0000100.#define
6a10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
6a20: 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 E_APPEND
6a30: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 0x00000200.#
6a40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6a50: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 CAP_SEQUENTIAL
6a60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6a70: 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 00400.#define SQ
6a80: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c LITE_IOCAP_UNDEL
6a90: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e ETABLE_WHEN_OPEN
6aa0: 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 0x00000800.#de
6ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6ac0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 P_POWERSAFE_OVER
6ad0: 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 WRITE 0x00001
6ae0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 000../*.** CAPI3
6af0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e REF: File Lockin
6b00: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 g Levels.**.** S
6b10: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f QLite uses one o
6b20: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 f these integer
6b30: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
6b40: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 cond.** argument
6b50: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b to calls it mak
6b60: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 es to the xLock(
6b70: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 ) and xUnlock()
6b80: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e methods.** of an
6b90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
6ba0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f hods] object..*/
6bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6bc0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 LOCK_NONE
6bd0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0.#define SQL
6be0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 ITE_LOCK_SHARED
6bf0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
6c00: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 SQLITE_LOCK_RES
6c10: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 ERVED 2.#de
6c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
6c30: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 _PENDING 3
6c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6c50: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 LOCK_EXCLUSIVE
6c60: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 4../*.** CAPI
6c70: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 3REF: Synchroniz
6c80: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 ation Type Flags
6c90: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 .**.** When SQLi
6ca0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 te invokes the x
6cb0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 Sync() method of
6cc0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
6cd0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
6ce0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d ct it uses a com
6cf0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 bination of.** t
6d00: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c hese integer val
6d10: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e ues as the secon
6d20: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
6d30: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 * When the SQLIT
6d40: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
6d50: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 flag is used, it
6d60: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a means that the.
6d70: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f ** sync operatio
6d80: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 n only needs to
6d90: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 flush data to ma
6da0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f ss storage. Ino
6db0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f de.** informatio
6dc0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c n need not be fl
6dd0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f ushed. If the lo
6de0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 wer four bits of
6df0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 the flag.** equ
6e00: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e al SQLITE_SYNC_N
6e10: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e ORMAL, that mean
6e20: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 s to use normal
6e30: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 fsync() semantic
6e40: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 s..** If the low
6e50: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 er four bits equ
6e60: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 al SQLITE_SYNC_F
6e70: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a ULL, that means.
6e80: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 ** to use Mac OS
6e90: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e X style fullsyn
6ea0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 c instead of fsy
6eb0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e nc()..**.** Do n
6ec0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 ot confuse the S
6ed0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 QLITE_SYNC_NORMA
6ee0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e L and SQLITE_SYN
6ef0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 C_FULL flags.**
6f00: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 with the [PRAGMA
6f10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f synchronous]=NO
6f20: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 RMAL and [PRAGMA
6f30: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 synchronous]=FU
6f40: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 LL.** settings.
6f50: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 The [synchronou
6f60: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d s pragma] determ
6f70: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 ines when calls
6f80: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 to the.** xSync
6f90: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 VFS method occur
6fa0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 and applies uni
6fb0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c formly across al
6fc0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 l platforms..**
6fd0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f The SQLITE_SYNC_
6fe0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
6ff0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
7000: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a s determine how.
7010: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 ** energetic or
7020: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 rigorous or forc
7030: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 eful the sync op
7040: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 erations are and
7050: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 .** only make a
7060: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 difference on Ma
7070: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 c OSX for the de
7080: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 fault SQLite cod
7090: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 e..** (Third-par
70a0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ty VFS implement
70b0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 ations might als
70c0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 o make the disti
70d0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 nction.** betwee
70e0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f n SQLITE_SYNC_NO
70f0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f RMAL and SQLITE_
7100: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 SYNC_FULL, but a
7110: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 mong the.** oper
7120: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 ating systems na
7130: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 tively supported
7140: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 by SQLite, only
7150: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 Mac OSX.** care
7160: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 s about the diff
7170: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 erence.).*/.#def
7180: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
7190: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 NORMAL 0x
71a0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
71b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 LITE_SYNC_FULL
71c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 0x00003.
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
71e0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 YNC_DATAONLY
71f0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 0x00010../*.**
7200: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e CAPI3REF: OS In
7210: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c terface Open Fil
7220: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 e Handle.**.** A
7230: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
7240: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e object represen
7250: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 ts an open file
7260: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 in the .** [sqli
7270: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 te3_vfs | OS int
7280: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 erface layer].
7290: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e Individual OS in
72a0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 terface.** imple
72b0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a mentations will.
72c0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c ** want to subcl
72d0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 ass this object
72e0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 by appending add
72f0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a itional fields.*
7300: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 * for their own
7310: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f use. The pMetho
7320: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f ds entry is a po
7330: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b inter to an.** [
7340: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7350: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 ds] object that
7360: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 defines methods
7370: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a for performing.*
7380: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 * I/O operations
7390: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c on the open fil
73a0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 e..*/.typedef st
73b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c ruct sqlite3_fil
73c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a e sqlite3_file;.
73d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
73e0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 ile {. const st
73f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
7400: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 methods *pMethod
7410: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 s; /* Methods f
7420: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 or an open file
7430: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
7440: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
7450: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c ace File Virtual
7460: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a Methods Object.
7470: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 **.** Every file
7480: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b opened by the [
7490: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
74a0: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 n] method popula
74b0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 tes an.** [sqlit
74c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
74d0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e (or, more common
74e0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f ly, a subclass o
74f0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
7500: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 3_file] object)
7510: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 with a pointer t
7520: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
7530: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a this object..**
7540: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 This object def
7550: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 ines the methods
7560: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d used to perform
7570: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 various operati
7580: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 ons.** against t
7590: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 he open file rep
75a0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 resented by the
75b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
75c0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 bject..**.** If
75d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
75e0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 .xOpen] method s
75f0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ets the sqlite3_
7600: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c file.pMethods el
7610: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e ement .** to a n
7620: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c on-NULL pointer,
7630: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 then the sqlite
7640: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 3_io_methods.xCl
7650: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 ose method.** ma
7660: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 y be invoked eve
7670: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 n if the [sqlite
7680: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 3_vfs.xOpen] rep
7690: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 orted that it fa
76a0: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e iled. The.** on
76b0: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e ly way to preven
76c0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f t a call to xClo
76d0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 se following a f
76e0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 ailed [sqlite3_v
76f0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 fs.xOpen].** is
7700: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
7710: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 _vfs.xOpen] to s
7720: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 et the sqlite3_f
7730: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
7740: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e ment.** to NULL.
7750: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
7760: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 argument to xSy
7770: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 nc may be one of
7780: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f [SQLITE_SYNC_NO
7790: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c RMAL] or.** [SQL
77a0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 ITE_SYNC_FULL].
77b0: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 The first choic
77c0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 e is the normal
77d0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 fsync()..** The
77e0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 second choice is
77f0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c a Mac OS X styl
7800: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 e fullsync. The
7810: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 [SQLITE_SYNC_DA
7820: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 TAONLY].** flag
7830: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 may be ORed in t
7840: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 o indicate that
7850: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 only the data of
7860: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 the file.** and
7870: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e not its inode n
7880: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 eeds to be synce
7890: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 d..**.** The int
78a0: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 eger values to x
78b0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
78c0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a ck() are one of.
78d0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
78e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e [SQLITE_LOCK_NON
78f0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c E],.** <li> [SQL
7900: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d ITE_LOCK_SHARED]
7910: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
7920: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d E_LOCK_RESERVED]
7930: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
7940: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c E_LOCK_PENDING],
7950: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c or.** <li> [SQL
7960: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 ITE_LOCK_EXCLUSI
7970: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a VE]..** </ul>.**
7980: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 xLock() increas
7990: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e es the lock. xUn
79a0: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 lock() decreases
79b0: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 the lock..** Th
79c0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 e xCheckReserved
79d0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 Lock() method ch
79e0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 ecks whether any
79f0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
7a00: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 tion,.** either
7a10: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 in this process
7a20: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 or in some other
7a30: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c process, is hol
7a40: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c ding a RESERVED,
7a50: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 .** PENDING, or
7a60: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f EXCLUSIVE lock o
7a70: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 n the file. It
7a80: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 returns true.**
7a90: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 if such a lock e
7aa0: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 xists and false
7ab0: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a otherwise..**.**
7ac0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f The xFileContro
7ad0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 l() method is a
7ae0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 generic interfac
7af0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 e that allows cu
7b00: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c stom.** VFS impl
7b10: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 ementations to d
7b20: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 irectly control
7b30: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 an open file usi
7b40: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
7b50: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
7b60: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 )] interface. T
7b70: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 he second "op" a
7b80: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a rgument is an.**
7b90: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e integer opcode.
7ba0: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 The third argu
7bb0: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 ment is a generi
7bc0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 c pointer intend
7bd0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 ed to.** point t
7be0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 o a structure th
7bf0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 at may contain a
7c00: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 rguments or spac
7c10: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a e in which to.**
7c20: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 write return va
7c30: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c lues. Potential
7c40: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 uses for xFileC
7c50: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 ontrol() might b
7c60: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 e.** functions t
7c70: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e o enable blockin
7c80: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d g locks with tim
7c90: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 eouts, to change
7ca0: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 the.** locking
7cb0: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 strategy (for ex
7cc0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 ample to use dot
7cd0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f -file locks), to
7ce0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 inquire.** abou
7cf0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 t the status of
7d00: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 a lock, or to br
7d10: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e eak stale locks.
7d20: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 The SQLite.**
7d30: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c core reserves al
7d40: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 l opcodes less t
7d50: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 han 100 for its
7d60: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 own use..** A [S
7d70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
7d80: 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 STATE | list of
7d90: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 opcodes] less th
7da0: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 an 100 is availa
7db0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ble..** Applicat
7dc0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 ions that define
7dd0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 a custom xFileC
7de0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 ontrol method sh
7df0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 ould use opcodes
7e00: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
7e10: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 100 to avoid co
7e20: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d nflicts. VFS im
7e30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
7e40: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
7e50: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
7e60: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f for file contro
7e70: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 l opcodes that t
7e80: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 hey do not.** re
7e90: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 cognize..**.** T
7ea0: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 he xSectorSize()
7eb0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
7ec0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 the sector size
7ed0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 of the.** device
7ee0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 that underlies
7ef0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 the file. The s
7f00: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 ector size is th
7f10: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 e.** minimum wri
7f20: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 te that can be p
7f30: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 erformed without
7f40: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f disturbing.** o
7f50: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 ther bytes in th
7f60: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 e file. The xDe
7f70: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
7f80: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ics().** method
7f90: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 returns a bit ve
7fa0: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 ctor describing
7fb0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 behaviors of the
7fc0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 .** underlying d
7fd0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c evice:.**.** <ul
7fe0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
7ff0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a E_IOCAP_ATOMIC].
8000: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8010: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d IOCAP_ATOMIC512]
8020: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8030: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d _IOCAP_ATOMIC1K]
8040: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8050: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d _IOCAP_ATOMIC2K]
8060: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8070: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d _IOCAP_ATOMIC4K]
8080: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d _IOCAP_ATOMIC8K]
80a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
80b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
80c0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
80d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
80e0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
80f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
8100: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
8110: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
8120: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b PPEND].** <li> [
8130: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
8140: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c UENTIAL].** </ul
8150: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
8160: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
8170: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8180: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
8190: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
81a0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
81b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
81c0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
81d0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
81e0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
81f0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
8200: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
8210: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
8220: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
8230: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
8240: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
8250: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8260: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
8270: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
8280: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
8290: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
82a0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
82b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
82c0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
82d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
82e0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
82f0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
8300: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
8310: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
8320: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
8330: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
8340: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
8350: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
8360: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
8370: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
8380: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
8390: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 *.** If xRead()
83a0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 returns SQLITE_I
83b0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
83c0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c it must also fil
83d0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 l.** in the unre
83e0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 ad portions of t
83f0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a he buffer with z
8400: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 eros. A VFS tha
8410: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 t.** fails to ze
8420: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
8430: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 ads might seem t
8440: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 o work. However
8450: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 ,.** failure to
8460: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
8470: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 reads will event
8480: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a ually lead to.**
8490: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
84a0: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
84b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
84c0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 io_methods sqlit
84d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 e3_io_methods;.s
84e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
84f0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
8500: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
8510: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
8520: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
8530: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 (*xRead)(sqlite
8540: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 3_file*, void*,
8550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
8560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
8570: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 int (*xWrite)(
8580: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 sqlite3_file*, c
8590: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
85a0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
85b0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
85c0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 t (*xTruncate)(s
85d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
85e0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 lite3_int64 size
85f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
8600: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8610: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 int flags);. i
8620: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 nt (*xFileSize)(
8630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
8640: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 qlite3_int64 *pS
8650: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
8660: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
8670: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
8680: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
8690: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
86a0: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
86b0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
86c0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a te3_file*, int *
86d0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
86e0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 (*xFileControl)(
86f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
8700: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 nt op, void *pAr
8710: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 g);. int (*xSec
8720: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 torSize)(sqlite3
8730: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
8740: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 *xDeviceCharacte
8750: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 ristics)(sqlite3
8760: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 _file*);. /* Me
8770: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
8780: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
8790: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 1 */. int (*x
87a0: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f ShmMap)(sqlite3_
87b0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 file*, int iPg,
87c0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 int pgsz, int, v
87d0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b oid volatile**);
87e0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 . int (*xShmLoc
87f0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
8800: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e , int offset, in
8810: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b t n, int flags);
8820: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 . void (*xShmBa
8830: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 rrier)(sqlite3_f
8840: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
8850: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 ShmUnmap)(sqlite
8860: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 3_file*, int del
8870: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d eteFlag);. /* M
8880: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8890: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
88a0: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 2 */. int (*
88b0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f xFetch)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
88d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 nt64 iOfst, int
88e0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 iAmt, void **pp)
88f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 ;. int (*xUnfet
8900: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
8910: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8920: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 iOfst, void *p)
8930: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
8940: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
8950: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a or version 3 */.
8960: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 /* Additional
8970: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 methods may be a
8980: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
8990: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f eleases */.};../
89a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
89b0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e tandard File Con
89c0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a trol Opcodes.**.
89d0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
89e0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f constants are o
89f0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 pcodes for the x
8a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
8a10: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 od.** of the [sq
8a20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
8a30: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 ] object and for
8a40: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
8a50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a le_control()].**
8a60: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
8a70: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
8a80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f NTL_LOCKSTATE] o
8a90: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f pcode is used fo
8aa0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 r debugging. Th
8ab0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 is.** opcode cau
8ac0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e ses the xFileCon
8ad0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 trol method to w
8ae0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 rite the current
8af0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 state of.** the
8b00: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 lock (one of [S
8b10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d QLITE_LOCK_NONE]
8b20: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 , [SQLITE_LOCK_S
8b30: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 HARED],.** [SQLI
8b40: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
8b50: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
8b60: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 PENDING], or [SQ
8b70: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
8b80: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e IVE]).** into an
8b90: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 integer that th
8ba0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 e pArg argument
8bb0: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 points to. This
8bc0: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 capability.** is
8bd0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
8be0: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 ting and only ne
8bf0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 eds to be suppor
8c00: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f ted when SQLITE_
8c10: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e TEST.** is defin
8c20: 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ed..** <ul>.** <
8c30: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
8c40: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a L_SIZE_HINT]].**
8c50: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
8c60: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 TL_SIZE_HINT] op
8c70: 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 code is used by
8c80: 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 SQLite to give t
8c90: 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 he VFS.** layer
8ca0: 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 a hint of how la
8cb0: 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 rge the database
8cc0: 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 file will grow
8cd0: 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 to be during the
8ce0: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e .** current tran
8cf0: 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 saction. This h
8d00: 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 int is not guara
8d10: 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 nteed to be accu
8d20: 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 rate but it.** i
8d30: 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 s often close.
8d40: 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 The underlying V
8d50: 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 FS might choose
8d60: 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 to preallocate d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 atabase.** file
8d80: 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 space based on t
8d90: 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 his hint in orde
8da0: 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 r to help writes
8db0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
8dc0: 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 .** file run fas
8dd0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ter..**.** <li>[
8de0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 [SQLITE_FCNTL_CH
8df0: 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 UNK_SIZE]].** Th
8e00: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
8e10: 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f CHUNK_SIZE] opco
8e20: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 de is used to re
8e30: 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 quest that the V
8e40: 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e FS.** extends an
8e50: 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 d truncates the
8e60: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e database file in
8e70: 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a chunks of a siz
8e80: 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 e specified.** b
8e90: 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 y the user. The
8ea0: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
8eb0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 to [sqlite3_file
8ec0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 _control()] shou
8ed0: 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 ld .** point to
8ee0: 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 an integer (type
8ef0: 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 int) containing
8f00: 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 the new chunk-s
8f10: 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f ize to use.** fo
8f20: 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 r the nominated
8f30: 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 database. Alloca
8f40: 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 ting database fi
8f50: 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 le space in larg
8f60: 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 e.** chunks (say
8f70: 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 1MB at a time),
8f80: 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 may reduce file
8f90: 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 -system fragment
8fa0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 ation and.** imp
8fb0: 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 rove performance
8fc0: 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 on some systems
8fd0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
8fe0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
8ff0: 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 POINTER]].** The
9000: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 [SQLITE_FCNTL_F
9010: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 ILE_POINTER] opc
9020: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f ode is used to o
9030: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a btain a pointer.
9040: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ** to the [sqlit
9050: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
9060: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
9070: 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
9080: 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
9090: 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 ion. See the [s
90a0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
90b0: 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 rol()] documenta
90c0: 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 tion for.** addi
90d0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
90e0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b on..**.** <li>[[
90f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
9100: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e C_OMITTED]].** ^
9110: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e (The [SQLITE_FCN
9120: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d TL_SYNC_OMITTED]
9130: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 opcode is gener
9140: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 ated internally
9150: 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 by.** SQLite and
9160: 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 sent to all VFS
9170: 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 es in place of a
9180: 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 call to the xSy
9190: 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 nc method.** whe
91a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
91b0: 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 onnection has [P
91c0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
91d0: 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e s] set to OFF.)^
91e0: 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c .** Some special
91f0: 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 ized VFSes need
9200: 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f this signal in o
9210: 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 rder to operate
9220: 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 correctly.** whe
9230: 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 n [PRAGMA synchr
9240: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 onous | PRAGMA s
9250: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 ynchronous=OFF]
9260: 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 is set, but most
9270: 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f .** VFSes do no
9280: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
9290: 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 al and should si
92a0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 lently ignore th
92b0: 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 is opcode..** Ap
92c0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
92d0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 d not call [sqli
92e0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
92f0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a ()] with this.**
9300: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 opcode as doing
9310: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 so may disrupt
9320: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 the operation of
9330: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
9340: 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 VFSes.** that d
9350: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a o require it. .
9360: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9370: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 TE_FCNTL_WIN32_A
9380: 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 V_RETRY]].** ^Th
9390: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
93a0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 WIN32_AV_RETRY]
93b0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
93c0: 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f o configure auto
93d0: 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 matic.** retry c
93e0: 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 ounts and interv
93f0: 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 als for certain
9400: 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 disk I/O operati
9410: 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 ons for the.** w
9420: 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 indows [VFS] in
9430: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 order to provide
9440: 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 robustness in t
9450: 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a he presence of.*
9460: 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f * anti-virus pro
9470: 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 grams. By defau
9480: 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 lt, the windows
9490: 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 VFS will retry f
94a0: 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c ile read,.** fil
94b0: 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c e write, and fil
94c0: 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 e delete operati
94d0: 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d ons up to 10 tim
94e0: 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 es, with a delay
94f0: 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 .** of 25 millis
9500: 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 econds before th
9510: 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e e first retry an
9520: 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 d with the delay
9530: 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 increasing.** b
9540: 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 y an additional
9550: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
9560: 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 with each subseq
9570: 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 uent retry. Thi
9580: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f s.** opcode allo
9590: 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c ws these two val
95a0: 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 ues (10 retries
95b0: 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f and 25 milliseco
95c0: 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a nds of delay).**
95d0: 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e to be adjusted.
95e0: 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 The values are
95f0: 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c changed for all
9600: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
9610: 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 tions.** within
9620: 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 the same process
9630: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 . The argument
9640: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
9650: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a an array of two.
9660: 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 ** integers wher
9670: 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 e the first inte
9680: 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 ger i the new re
9690: 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 try count and th
96a0: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 e second.** inte
96b0: 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 ger is the delay
96c0: 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 . If either int
96d0: 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 eger is negative
96e0: 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 , then the setti
96f0: 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 ng.** is not cha
9700: 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 nged but instead
9710: 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
9720: 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 of that setting
9730: 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 is written.** i
9740: 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e nto the array en
9750: 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 try, allowing th
9760: 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 e current retry
9770: 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a settings to be.*
9780: 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 * interrogated.
9790: 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 The zDbName par
97a0: 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 ameter is ignore
97b0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
97c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
97d0: 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 IST_WAL]].** ^Th
97e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
97f0: 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 PERSIST_WAL] opc
9800: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 ode is used to s
9810: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a et or query the.
9820: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 ** persistent [W
9830: 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 AL | Write Ahead
9840: 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 Log] setting.
9850: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
9860: 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 auxiliary.** wri
9870: 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 te ahead log and
9880: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
9890: 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 iles used for tr
98a0: 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f ansaction contro
98b0: 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 l.** are automat
98c0: 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 ically deleted w
98d0: 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 hen the latest c
98e0: 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 onnection to the
98f0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f database.** clo
9900: 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 ses. Setting pe
9910: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 rsistent WAL mod
9920: 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 e causes those f
9930: 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 iles to persist
9940: 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 after.** close.
9950: 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 Persisting the
9960: 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 files is useful
9970: 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 when other proce
9980: 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 sses that do not
9990: 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 .** have write p
99a0: 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 ermission on the
99b0: 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 directory conta
99c0: 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 ining the databa
99d0: 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 se file want.**
99e0: 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 to read the data
99f0: 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 base file, as th
9a00: 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 e WAL and shared
9a10: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 memory files mu
9a20: 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f st exist.** in o
9a30: 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 rder for the dat
9a40: 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 abase to be read
9a50: 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 able. The fourt
9a60: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a h parameter to.*
9a70: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
9a80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 control()] for t
9a90: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c his opcode shoul
9aa0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 d be a pointer t
9ab0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a o an integer..**
9ac0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 That integer is
9ad0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 0 to disable pe
9ae0: 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 rsistent WAL mod
9af0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 e or 1 to enable
9b00: 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 persistent.** W
9b10: 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 AL mode. If the
9b20: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 integer is -1,
9b30: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 then it is overw
9b40: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
9b50: 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 current.** WAL p
9b60: 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 ersistence setti
9b70: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ng..**.** <li>[[
9b80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
9b90: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
9ba0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
9bb0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
9bc0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 FE_OVERWRITE] op
9bd0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
9be0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 set or query the
9bf0: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 .** persistent "
9c00: 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 powersafe-overwr
9c10: 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 ite" or "PSOW" s
9c20: 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f etting. The PSO
9c30: 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 W setting.** det
9c40: 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c ermines the [SQL
9c50: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 ITE_IOCAP_POWERS
9c60: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 AFE_OVERWRITE] b
9c70: 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 it of the.** xDe
9c80: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
9c90: 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 ics methods. The
9ca0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
9cb0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
9cc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
9cd0: 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
9ce0: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 should be a poi
9cf0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
9d00: 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 er..** That inte
9d10: 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 ger is 0 to disa
9d20: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 ble zero-damage
9d30: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 mode or 1 to ena
9d40: 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a ble zero-damage.
9d50: 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 ** mode. If the
9d60: 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 integer is -1,
9d70: 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 then it is overw
9d80: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
9d90: 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d current.** zero-
9da0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 damage mode sett
9db0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ing..**.** <li>[
9dc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 [SQLITE_FCNTL_OV
9dd0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
9de0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9df0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 OVERWRITE] opcod
9e00: 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 e is invoked by
9e10: 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 SQLite after ope
9e20: 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 ning.** a write
9e30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 transaction to i
9e40: 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e ndicate that, un
9e50: 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 less it is rolle
9e60: 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a d back for some.
9e70: 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 ** reason, the e
9e80: 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 ntire database f
9e90: 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 ile will be over
9ea0: 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 written by the c
9eb0: 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 urrent .** trans
9ec0: 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 action. This is
9ed0: 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f used by VACUUM o
9ee0: 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a perations..**.**
9ef0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9f00: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a NTL_VFSNAME]].**
9f10: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
9f20: 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 NTL_VFSNAME] opc
9f30: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ode can be used
9f40: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 to obtain the na
9f50: 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 mes of.** all [V
9f60: 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 FSes] in the VFS
9f70: 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d stack. The nam
9f80: 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 es are of all VF
9f90: 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a S shims and the.
9fa0: 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d ** final bottom-
9fb0: 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 level VFS are wr
9fc0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
9fd0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
9fe0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
9ff0: 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 loc()] and the r
a000: 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 esult is stored
a010: 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 in the char* var
a020: 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 iable.** that th
a030: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
a040: 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 er of [sqlite3_f
a050: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 ile_control()] p
a060: 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 oints to..** The
a070: 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f caller is respo
a080: 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 nsible for freei
a090: 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 ng the memory wh
a0a0: 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 en done. As wit
a0b0: 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f h.** all file-co
a0c0: 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 ntrol actions, t
a0d0: 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 here is no guara
a0e0: 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 ntee that this w
a0f0: 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 ill actually.**
a100: 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 do anything. Ca
a110: 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 llers should ini
a120: 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 tialize the char
a130: 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 * variable to a
a140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
a150: 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c in case this fil
a160: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 e-control is not
a170: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 implemented. T
a180: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
a190: 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 .** is intended
a1a0: 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 for diagnostic u
a1b0: 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c se only..**.** <
a1c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
a1d0: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 L_PRAGMA]].** ^W
a1e0: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d henever a [PRAGM
a1f0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 A] statement is
a200: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 parsed, an [SQLI
a210: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
a220: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f .** file contro
a230: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 l is sent to the
a240: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 open [sqlite3_f
a250: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 ile] object corr
a260: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 esponding.** to
a270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
a280: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 e to which the p
a290: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 ragma statement
a2a0: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 refers. ^The arg
a2b0: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 ument.** to the
a2c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
a2d0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
a2e0: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ol is an array o
a2f0: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f f.** pointers to
a300: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a strings (char**
a310: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 ) in which the s
a320: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 econd element of
a330: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 the array.** is
a340: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
a350: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 pragma and the
a360: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 third element is
a370: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
a380: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f the.** pragma o
a390: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 r NULL if the pr
a3a0: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 agma has no argu
a3b0: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 ment. ^The hand
a3c0: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 ler for an.** [S
a3d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a3e0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
a3f0: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 can optionally
a400: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 make the first e
a410: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 lement.** of the
a420: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 char** argument
a430: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 point to a stri
a440: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ng obtained from
a450: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 [sqlite3_mprint
a460: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 f()].** or the e
a470: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 quivalent and th
a480: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 at string will b
a490: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 ecome the result
a4a0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f of the pragma o
a4b0: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d r.** the error m
a4c0: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 essage if the pr
a4d0: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 agma fails. ^If
a4e0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 the.** [SQLITE_F
a4f0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
a500: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
a510: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 s [SQLITE_NOTFOU
a520: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c ND], then normal
a530: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 .** [PRAGMA] pr
a540: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 ocessing continu
a550: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 es. ^If the [SQ
a560: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
a570: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 A].** file contr
a580: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ol returns [SQLI
a590: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 TE_OK], then the
a5a0: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 parser assumes
a5b0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 that the.** VFS
a5c0: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 has handled the
a5d0: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e PRAGMA itself an
a5e0: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e d the parser gen
a5f0: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a erates a no-op.*
a600: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
a610: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b ment. ^If the [
a620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
a630: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f GMA] file contro
a640: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 l returns.** any
a650: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 result code oth
a660: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
a670: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e OK] or [SQLITE_N
a680: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d OTFOUND], that m
a690: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 eans.** that the
a6a0: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 VFS encountered
a6b0: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 an error while
a6c0: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 handling the [PR
a6d0: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a AGMA] and the.**
a6e0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 compilation of
a6f0: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 the PRAGMA fails
a700: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 with an error.
a710: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
a720: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 NTL_PRAGMA].** f
a730: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 ile control occu
a740: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e rs at the beginn
a750: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 ing of pragma st
a760: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 atement analysis
a770: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 and so.** it is
a780: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 able to overrid
a790: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 e built-in [PRAG
a7a0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a MA] statements..
a7b0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a7c0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e TE_FCNTL_BUSYHAN
a7d0: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b DLER]].** ^The [
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 SQLITE_FCNTL_BUS
a7f0: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c YHANDLER].** fil
a800: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 e-control may be
a810: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
a820: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 te on the databa
a830: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a se file handle.*
a840: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 * shortly after
a850: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 it is opened in
a860: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 order to provide
a870: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 a custom VFS wi
a880: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 th access.** to
a890: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 the connections
a8a0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c busy-handler cal
a8b0: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d lback. The argum
a8c0: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 ent is of type (
a8d0: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e void **).** - an
a8e0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 array of two (v
a8f0: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 oid *) values. T
a900: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a he first (void *
a910: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 ) actually point
a920: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 s.** to a functi
a930: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 on of type (int
a940: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e (*)(void *)). In
a950: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 order to invoke
a960: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 the connections
a970: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 .** busy-handler
a980: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 , this function
a990: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 should be invoke
a9a0: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e d with the secon
a9b0: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a d (void *) in.**
a9c0: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 the array as th
a9d0: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e e only argument.
a9e0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e If it returns n
a9f0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 on-zero, then th
aa00: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 e operation.** s
aa10: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 hould be retried
aa20: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 . If it returns
aa30: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d zero, the custom
aa40: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e VFS should aban
aa50: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 don the.** curre
aa60: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a nt operation..**
aa70: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
aa80: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
aa90: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 AME]].** ^Applic
aaa0: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 ation can invoke
aab0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
aac0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d TL_TEMPFILENAME]
aad0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a file-control.**
aae0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 to have SQLite
aaf0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 generate a.** te
ab00: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 mporary filename
ab10: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 using the same
ab20: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 algorithm that i
ab30: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 s followed to ge
ab40: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 nerate.** tempor
ab50: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f ary filenames fo
ab60: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e r TEMP tables an
ab70: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c d other internal
ab80: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 uses. The.** a
ab90: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 rgument should b
aba0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 e a char** which
abb0: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 will be filled
abc0: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d with the filenam
abd0: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 e.** written int
abe0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
abf0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
ac00: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 malloc()]. The
ac10: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a caller should.**
ac20: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 invoke [sqlite3
ac30: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 _free()] on the
ac40: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 result to avoid
ac50: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a a memory leak..*
ac60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
ac70: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
ac80: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
ac90: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
aca0: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c ZE] file control
acb0: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 is used to quer
acc0: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 y or set the.**
acd0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
ace0: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c f bytes that wil
acf0: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 l be used for me
ad00: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e mory-mapped I/O.
ad10: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
ad20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
ad30: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 a value of type
ad40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 sqlite3_int64 t
ad50: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 hat.** is an adv
ad60: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 isory maximum nu
ad70: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
ad80: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d the file to mem
ad90: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a ory map. The.**
ada0: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 pointer is over
adb0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 written with the
adc0: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 old value. The
add0: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 limit is not ch
ade0: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 anged if.** the
adf0: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 value originally
ae00: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e pointed to is n
ae10: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 egative, and so
ae20: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 the current limi
ae30: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 t .** can be que
ae40: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ried by passing
ae50: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 in a pointer to
ae60: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 a negative numbe
ae70: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 r. This.** file
ae80: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 -control is used
ae90: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 internally to i
aea0: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 mplement [PRAGMA
aeb0: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a mmap_size]..**.
aec0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
aed0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a FCNTL_TRACE]].**
aee0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
aef0: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 TL_TRACE] file c
af00: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 ontrol provides
af10: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 advisory informa
af20: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 tion.** to the V
af30: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 FS about what th
af40: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 e higher layers
af50: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 of the SQLite st
af60: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a ack are doing..*
af70: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 * This file cont
af80: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 rol is used by s
af90: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 ome VFS activity
afa0: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d tracing [shims]
afb0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e ..** The argumen
afc0: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d t is a zero-term
afd0: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 inated string.
afe0: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e Higher layers in
aff0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 the.** SQLite s
b000: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 tack may generat
b010: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 e instances of t
b020: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c his file control
b030: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 if.** the [SQLI
b040: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 TE_USE_FCNTL_TRA
b050: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 CE] compile-time
b060: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c option is enabl
b070: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a ed..**.** </ul>.
b080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
b090: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
b0a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
b0b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
b0c0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
b0d0: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 LE 2
b0e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b0f0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
b100: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a E 3.
b110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
b120: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
b130: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 4.#
b140: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
b150: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 NTL_SIZE_HINT
b160: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
b170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
b180: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 TL_CHUNK_SIZE
b190: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
b1a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
b1b0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 L_FILE_POINTER
b1c0: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
b1d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
b1e0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 _SYNC_OMITTED
b1f0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 8.#defi
b200: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
b210: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 WIN32_AV_RETRY
b220: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
b230: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
b240: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 ERSIST_WAL
b250: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 10.#define
b260: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 SQLITE_FCNTL_OV
b270: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 ERWRITE
b280: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 11.#define
b290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
b2a0: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 NAME
b2b0: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 12.#define S
b2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
b2d0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
b2e0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 13.#define SQ
b2f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
b300: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
b310: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 14.#define SQL
b320: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
b330: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 NDLER
b340: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 15.#define SQLI
b350: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
b360: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 ENAME
b370: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 16.#define SQLIT
b380: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
b390: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 E 1
b3a0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 _FCNTL_TRACE
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
b3d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
b3e0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a : Mutex Handle.*
b3f0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
b400: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
b410: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
b420: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
b430: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
b440: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
b450: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
b460: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
b470: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
b480: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
b490: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
b4a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
b4b0: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
b4c0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
b4d0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
b4e0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
b4f0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
b500: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
b510: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
b520: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
b530: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
b540: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
b550: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
b560: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
b570: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
b580: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
b590: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
b5a0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
b5b0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
b5c0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
b5d0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
b5e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
b5f0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
b600: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
b610: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
b620: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
b630: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
b640: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
b650: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
b660: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
b670: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
b680: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
b690: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
b6a0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
b6b0: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
b6c0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
b6d0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
b6e0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
b6f0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
b700: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
b710: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
b720: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
b730: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
b740: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
b750: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
b760: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
b770: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
b780: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
b790: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
b7a0: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
b7b0: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
b7c0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
b7d0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
b7e0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
b7f0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
b800: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
b810: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
b820: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
b830: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
b840: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
b850: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
b860: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
b870: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
b880: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
b890: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
b8a0: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
b8b0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
b8c0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
b8d0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
b8e0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
b8f0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
b900: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
b910: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
b920: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
b930: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
b940: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
b950: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
b960: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
b970: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
b980: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
b990: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
b9a0: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
b9b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
b9c0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
b9d0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
b9e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
b9f0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
ba00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
ba10: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
ba20: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
ba30: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
ba40: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
ba50: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
ba60: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
ba70: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
ba80: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
ba90: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
baa0: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
bab0: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
bac0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
bad0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
bae0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
baf0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
bb00: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
bb10: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
bb20: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
bb30: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
bb40: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
bb50: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
bb60: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
bb70: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
bb80: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
bb90: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
bba0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 es..**.** [[sqli
bbb0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a te3_vfs.xOpen]].
bbc0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
bbd0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a ntees that the z
bbe0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
bbf0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 er to xOpen.** i
bc00: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
bc10: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e pointer or strin
bc20: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 g obtained.** fr
bc30: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 om xFullPathname
bc40: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f () with an optio
bc50: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 nal suffix added
bc60: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 ..** ^If a suffi
bc70: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 x is added to th
bc80: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
bc90: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a meter, it will.*
bca0: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 * consist of a s
bcb0: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 ingle "-" charac
bcc0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 ter followed by
bcd0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 no more than.**
bce0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 11 alphanumeric
bcf0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 and/or "-" chara
bd00: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 cters..** ^SQLit
bd10: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
bd20: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
bd30: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
bd40: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
bd50: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
bd60: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
bd70: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
bd80: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
bd90: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
bda0: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
bdb0: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
bdc0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
bdd0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
bde0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
bdf0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
be00: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
be10: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
be20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
be30: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
be40: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
be50: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 .** must invent
be60: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
be70: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
be80: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 ile. ^Whenever
be90: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d the .** xFilenam
bea0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e e parameter is N
beb0: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f ULL it will also
bec0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
bed0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 t the.** flags p
bee0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e arameter will in
bef0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
bf00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
bf10: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 ]..**.** The fla
bf20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
bf30: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 Open() includes
bf40: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a all bits set in.
bf50: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 ** the flags arg
bf60: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
bf70: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 3_open_v2()]. O
bf80: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r if [sqlite3_op
bf90: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c en()].** or [sql
bfa0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 ite3_open16()] i
bfb0: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
bfc0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c gs includes at l
bfd0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f east.** [SQLITE_
bfe0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
bff0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
c000: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 REATE]. .** If x
c010: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 Open() opens a f
c020: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 ile read-only th
c030: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 en it sets *pOut
c040: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c Flags to.** incl
c050: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
c060: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 _READONLY]. Oth
c070: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 er bits in *pOut
c080: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 Flags may be set
c090: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 ..**.** ^(SQLite
c0a0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
c0b0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
c0c0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
c0d0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
c0e0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
c0f0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
c100: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
c110: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
c120: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
c130: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
c140: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
c150: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
c160: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
c170: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
c180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
c190: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
c1a0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
c1b0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
c1c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
c1d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
c1e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
c1f0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
c200: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
c210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a QLITE_OPEN_WAL].
c220: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
c230: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
c240: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
c250: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
c260: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
c270: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
c280: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
c290: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
c2a0: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
c2b0: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
c2c0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
c2d0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
c2e0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
c2f0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
c300: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
c310: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
c320: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
c330: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
c340: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
c350: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
c360: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
c370: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
c380: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
c390: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
c3a0: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
c3b0: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
c3c0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
c3d0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
c3e0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
c3f0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
c400: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
c410: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
c420: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
c430: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
c440: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
c450: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
c460: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
c470: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
c480: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
c490: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
c4a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
c4b0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
c4c0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
c4d0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
c4e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
c4f0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
c500: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
c510: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
c520: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
c530: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
c540: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 sed. ^The [SQLI
c550: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
c560: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 CLOSE].** will b
c570: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 e set for TEMP d
c580: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 atabases and the
c590: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 ir journals, tra
c5a0: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 nsient.** databa
c5b0: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 ses, and subjour
c5c0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nals..**.** ^The
c5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
c5e0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 CLUSIVE] flag is
c5f0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 always used in
c600: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 conjunction.** w
c610: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
c620: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 OPEN_CREATE] fla
c630: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 g, which are bot
c640: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e h directly.** an
c650: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f alogous to the O
c660: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 _EXCL and O_CREA
c670: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 T flags of the P
c680: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 OSIX open().** A
c690: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f PI. The SQLITE_
c6a0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 OPEN_EXCLUSIVE f
c6b0: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 lag, when paired
c6c0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 with the .** SQ
c6d0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
c6e0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 , is used to ind
c6f0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 icate that file
c700: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a should always.**
c710: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 be created, and
c720: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 that it is an e
c730: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 rror if it alrea
c740: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 dy exists..** It
c750: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 is <i>not</i> u
c760: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
c770: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
c780: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f be opened .** fo
c790: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
c7a0: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 ss..**.** ^At le
c7b0: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
c7c0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
c7d0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
c7e0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
c7f0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
c800: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
c810: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
c820: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
c830: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 xOpen. The xOp
c840: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
c850: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
c860: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
c870: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
c880: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
c890: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 Note that.** t
c8a0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
c8b0: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c must set the sql
c8c0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
c8d0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 ds to either.**
c8e0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 a valid [sqlite3
c8f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
c900: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 ect or to NULL.
c910: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a xOpen must do.*
c920: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 * this even if t
c930: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 he open fails.
c940: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 SQLite expects t
c950: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f hat the sqlite3_
c960: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a file.pMethods.**
c970: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 element will be
c980: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 valid after xOp
c990: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 en returns regar
c9a0: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
c9b0: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 cess.** or failu
c9c0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 re of the xOpen
c9d0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 call..**.** [[sq
c9e0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 lite3_vfs.xAcces
c9f0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 s]].** ^The flag
ca00: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
ca10: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
ca20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
ca30: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
ca40: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
ca50: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
ca60: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
ca70: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
ca80: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
ca90: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
caa0: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
cab0: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
cac0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
cad0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
cae0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
caf0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
cb00: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
cb10: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e rectory..**.** ^
cb20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 SQLite will alwa
cb30: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c ys allocate at l
cb40: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b east mxPathname+
cb50: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 1 bytes for the.
cb60: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ** output buffer
cb70: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 xFullPathname.
cb80: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 The exact size
cb90: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 of the output bu
cba0: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 ffer.** is also
cbb0: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 passed as a para
cbc0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d meter to both m
cbd0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f ethods. If the o
cbe0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
cbf0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
cc00: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
cc10: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
cc20: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
cc30: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
cc40: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
cc50: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
cc60: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
cc70: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
cc80: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
cc90: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
cca0: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
ccb0: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
ccc0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
ccd0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
cce0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 s(), xSleep(), x
ccf0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 CurrentTime(), a
cd00: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 nd xCurrentTimeI
cd10: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 nt64().** interf
cd20: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 aces are not str
cd30: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 ictly a part of
cd40: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 the filesystem,
cd50: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 but they are.**
cd60: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 included in the
cd70: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f VFS structure fo
cd80: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a r completeness..
cd90: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
cda0: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 ss() function at
cdb0: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e tempts to return
cdc0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a nBytes bytes.**
cdd0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 of good-quality
cde0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
cdf0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 zOut. The retu
ce00: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 rn value is.** t
ce10: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 he actual number
ce20: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e of bytes of ran
ce30: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
ce40: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 ..** The xSleep(
ce50: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 ) method causes
ce60: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
ce70: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 ad to sleep for
ce80: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 at.** least the
ce90: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 number of micros
cea0: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e econds given. ^
ceb0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
cec0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
ced0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
cee0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
cef0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
cf00: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 d time as.** a f
cf10: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
cf20: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 lue..** ^The xCu
cf30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
cf40: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c method returns,
cf50: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 as an integer,
cf60: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 the Julian.** Da
cf70: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c y Number multipl
cf80: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 ied by 86400000
cf90: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d (the number of m
cfa0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a illiseconds in .
cfb0: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 ** a 24-hour day
cfc0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ). .** ^SQLite
cfd0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 will use the xCu
cfe0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
cff0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 method to get t
d000: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 he current.** da
d010: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 te and time if t
d020: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 hat method is av
d030: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 ailable (if iVer
d040: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a sion is 2 or .**
d050: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 greater and the
d060: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
d070: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 r is not NULL) a
d080: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 nd will fall bac
d090: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 k.** to xCurrent
d0a0: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 Time() if xCurre
d0b0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 ntTimeInt64() is
d0c0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
d0d0: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 .** ^The xSetSys
d0e0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 temCall(), xGetS
d0f0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 ystemCall(), and
d100: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c xNestSystemCall
d110: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
d120: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 are not used by
d130: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
d140: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 . These optiona
d150: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 l interfaces are
d160: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 provided.** by
d170: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 some VFSes to fa
d180: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 cilitate testing
d190: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 of the VFS code
d1a0: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 . By overriding
d1b0: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 .** system calls
d1c0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 with functions
d1d0: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f under its contro
d1e0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 l, a test progra
d1f0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 m can.** simulat
d200: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 e faults and err
d210: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 or conditions th
d220: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 at would otherwi
d230: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a se be difficult.
d240: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 ** or impossible
d250: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 to induce. The
d260: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 set of system c
d270: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 alls that can be
d280: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 overridden.** v
d290: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 aries from one V
d2a0: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 FS to another, a
d2b0: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 nd from one vers
d2c0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ion of the same
d2d0: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 VFS to the.** ne
d2e0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
d2f0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 s that use these
d300: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 interfaces must
d310: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 be prepared for
d320: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f any.** or all o
d330: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 f these interfac
d340: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 es to be NULL or
d350: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 for their behav
d360: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ior to change.**
d370: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 from one releas
d380: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 e to the next.
d390: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 Applications mus
d3a0: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f t not attempt to
d3b0: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f access.** any o
d3c0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 f these methods
d3d0: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 if the iVersion
d3e0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 of the VFS is le
d3f0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 ss than 3..*/.ty
d400: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
d410: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
d420: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f _vfs;.typedef vo
d430: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 id (*sqlite3_sys
d440: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b call_ptr)(void);
d450: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
d460: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
d470: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
d480: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
d490: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 rsion number (cu
d4a0: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 rrently 3) */.
d4b0: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
d4c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
d4d0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
d4e0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
d4f0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
d500: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
d510: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
d520: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
d530: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
d540: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
d550: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
d560: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
d570: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
d580: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
d590: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
d5a0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
d5b0: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
d5c0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
d5d0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
d5e0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
d5f0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
d600: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
d610: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
d620: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
d630: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
d640: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
d650: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
d660: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
d670: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
d680: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
d690: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
d6a0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
d6b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
d6c0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
d6d0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
d6e0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
d6f0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
d700: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
d710: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
d720: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
d730: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
d740: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
d750: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
d760: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
d770: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
d780: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
d790: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
d7a0: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
d7b0: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
d7c0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
d7d0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
d7e0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
d7f0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
d800: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
d810: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
d820: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
d830: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
d840: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
d850: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
d860: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
d870: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
d880: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
d890: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
d8a0: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
d8b0: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
d8c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
d8d0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
d8e0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
d8f0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
d900: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 version 1 of th
d910: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
d920: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 ect. ** definit
d930: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 ion. Those that
d940: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 follow are adde
d950: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f d in version 2 o
d960: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 r later. */. i
d970: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
d980: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f eInt64)(sqlite3_
d990: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e vfs*, sqlite3_in
d9a0: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a t64*);. /*. **
d9b0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
d9c0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
d9d0: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 ns 1 and 2 of th
d9e0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
d9f0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 ect.. ** Those
da00: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 below are for ve
da10: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 rsion 3 and grea
da20: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 ter.. */. int
da30: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xSetSystemCall
da40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
da50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
da60: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 e, sqlite3_sysca
da70: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 ll_ptr);. sqlit
da80: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 e3_syscall_ptr (
da90: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xGetSystemCall)
daa0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
dab0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
dac0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 );. const char
dad0: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 *(*xNextSystemCa
dae0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
daf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
db00: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 ame);. /*. **
db10: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
db20: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
db30: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 s 1 through 3 of
db40: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
db50: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 object.. ** New
db60: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
db70: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
db80: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
db90: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
dba0: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
dbb0: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
dbc0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f s happens. . */
dbd0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
dbe0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
dbf0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
dc00: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
dc10: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
dc20: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
dc30: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
dc40: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
dc50: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
dc60: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
dc70: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 fs] object. The
dc80: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
dc90: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
dca0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
dcb0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
dcc0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
dcd0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
dce0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
dcf0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
dd00: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
dd10: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
dd20: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
dd30: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
dd40: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
dd50: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
dd60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
dd70: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 named directory
dd80: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
dd90: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a and writable.**
dda0: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 (in other words
ddb0: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 , if files can b
ddc0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 e added, removed
ddd0: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 , and renamed wi
dde0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 thin.** the dire
ddf0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 ctory)..** The S
de00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
de10: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 DWRITE constant
de20: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 is currently use
de30: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a d only by the.**
de40: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
de50: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 ectory pragma],
de60: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c though this coul
de70: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 d change in a fu
de80: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
de90: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 of SQLite..** Wi
dea0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
deb0: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 _READ, the xAcce
dec0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
ded0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
dee0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
def0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
df00: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 CESS_READ consta
df10: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 nt is.** current
df20: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 ly unused, thoug
df30: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 h it might be us
df40: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 ed in a future r
df50: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
df60: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
df70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
df80: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
df90: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
dfa0: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a READWRITE 1 /*
dfb0: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 Used by PRAGMA
dfc0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
dfd0: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tory */.#define
dfe0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
dff0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 AD 2 /* U
e000: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nused */../*.**
e010: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
e020: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b for the xShmLock
e030: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
e040: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
e050: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
e060: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 the various loc
e070: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a king operations.
e080: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 ** allowed by th
e090: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
e0a0: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f d of [sqlite3_io
e0b0: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a _methods]. The.
e0c0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 ** following are
e0d0: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 the only legal
e0e0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 combinations of
e0f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 flags to the.**
e100: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a xShmLock method:
e110: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
e120: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
e130: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
e140: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
e150: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
e160: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
e170: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e XCLUSIVE.** <li>
e180: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
e190: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
e1a0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
e1b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
e1c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
e1d0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 EXCLUSIVE.** </u
e1e0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e l>.**.** When un
e1f0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d locking, the sam
e200: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c e SHARED or EXCL
e210: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 USIVE flag must
e220: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a be supplied as.*
e230: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 * was given no t
e240: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
e250: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 lock. .**.** T
e260: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
e270: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f od can transitio
e280: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b n between unlock
e290: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 ed and SHARED or
e2a0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f .** between unlo
e2b0: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 cked and EXCLUSI
e2c0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 VE. It cannot t
e2d0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
e2e0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 n SHARED.** and
e2f0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 EXCLUSIVE..*/.#d
e300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
e310: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a _UNLOCK 1.
e320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
e330: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 HM_LOCK
e340: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
e350: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 _SHM_SHARED
e360: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
e370: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
e380: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
e390: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 I3REF: Maximum x
e3a0: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a ShmLock index.**
e3b0: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
e3c0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 method on [sqli
e3d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
e3e0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a may use values.*
e3f0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
e400: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 this upper bound
e410: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 as its "offset"
e420: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
e430: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
e440: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 ll never attempt
e450: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 to acquire or r
e460: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b elease a.** lock
e470: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 outside of this
e480: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e range.*/.#defin
e490: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f e SQLITE_SHM_NLO
e4a0: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a CK 8.../*
e4b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
e4c0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
e4d0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
e4e0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
e4f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
e500: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 ine initializes
e510: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 the.** SQLite li
e520: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c brary. ^The sql
e530: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
e540: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
e550: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
e560: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
e570: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
e580: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
e590: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
e5a0: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 nes are designed
e5b0: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 to aid in proce
e5c0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
e5d0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 n and.** shutdow
e5e0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 n on embedded sy
e5f0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 stems. Workstat
e600: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ion applications
e610: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 using.** SQLite
e620: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 normally do not
e630: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 need to invoke
e640: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 either of these
e650: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
e660: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
e670: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
e680: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
e690: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
e6a0: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
e6b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
e6c0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
e6d0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
e6e0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
e6f0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
e700: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
e710: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
e720: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
e730: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
e740: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
e750: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 3_shutdown(). ^
e760: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 (Only an effecti
e770: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 ve call.** of sq
e780: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
e790: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 () does any init
e7a0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c ialization. All
e7b0: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 other calls.**
e7c0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
e7d0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 ops.)^.**.** A c
e7e0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
e7f0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 hutdown() is an
e800: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
e810: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
e820: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 rst.** call to s
e830: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
e840: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 ) since the last
e850: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
e860: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a ize(). ^(Only.*
e870: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 * an effective c
e880: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
e890: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 hutdown() does a
e8a0: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 ny deinitializat
e8b0: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 ion..** All othe
e8c0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f r valid calls to
e8d0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
e8e0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
e8f0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
e900: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
e910: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 tialize() interf
e920: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ace is threadsaf
e930: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 e, but sqlite3_s
e940: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 hutdown().** is
e950: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 not. The sqlite
e960: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 3_shutdown() int
e970: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 erface must only
e980: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
e990: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 a.** single thre
e9a0: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 ad. All open [d
e9b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
e9c0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f ons] must be clo
e9d0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f sed and all.** o
e9e0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f ther SQLite reso
e9f0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 urces must be de
ea00: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 allocated prior
ea10: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 to invoking.** s
ea20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
ea30: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f )..**.** Among o
ea40: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 ther things, ^sq
ea50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
ea60: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
ea70: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
ea80: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
ea90: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f ^sqlite3_shutdo
eaa0: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
eab0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
eac0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nd()..**.** ^The
ead0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
eae0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ize() routine re
eaf0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
eb00: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a ] on success..**
eb10: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 ^If for some re
eb20: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
eb30: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
eb40: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
eb50: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
eb60: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
eb70: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
eb80: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
eb90: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
eba0: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
ebb0: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
ebc0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
ebd0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
ebe0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
ebf0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
ec00: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 tine is called i
ec10: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e nternally by man
ec20: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 y other.** SQLit
ec30: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 e interfaces so
ec40: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 that an applicat
ec50: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 ion usually does
ec60: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 not need to.**
ec70: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
ec80: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
ec90: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 ctly. For examp
eca0: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 le, [sqlite3_ope
ecb0: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 n()].** calls sq
ecc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
ecd0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 () so the SQLite
ece0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 library will be
ecf0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
ed00: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 * initialized wh
ed10: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e en [sqlite3_open
ed20: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 ()] is called if
ed30: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 it has not be i
ed40: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c nitialized.** al
ed50: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 ready. ^However
ed60: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
ed70: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
ed80: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
ed90: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
eda0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
edb0: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
edc0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
edd0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
ede0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
edf0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
ee00: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
ee10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
ee20: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
ee30: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
ee40: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
ee50: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
ee60: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
ee70: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
ee80: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
ee90: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
eea0: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
eeb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
eec0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
eed0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
eee0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
eef0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
ef00: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
ef10: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
ef20: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
ef30: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
ef40: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
ef50: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
ef60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
ef70: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
ef80: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
ef90: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
efa0: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
efb0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
efc0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
efd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
efe0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
eff0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
f000: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
f010: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
f020: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
f030: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
f040: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
f050: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
f060: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
f070: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
f080: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
f090: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
f0a0: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
f0b0: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
f0c0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
f0d0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
f0e0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
f0f0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
f100: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
f110: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
f120: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
f130: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
f140: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
f150: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
f160: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
f170: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
f180: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
f190: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
f1a0: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
f1b0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
f1c0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
f1d0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
f1e0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
f1f0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
f200: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
f210: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
f220: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
f230: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
f240: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
f250: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
f260: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
f270: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
f280: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
f290: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
f2a0: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
f2b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f2c0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
f2d0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
f2e0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
f2f0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
f300: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
f310: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
f320: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
f330: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 s compiled for U
f340: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 nix, Windows, or
f350: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b OS/2..** When [
f360: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 custom builds |
f370: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 built for other
f380: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 platforms].** (u
f390: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
f3a0: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d _OS_OTHER=1] com
f3b0: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
f3c0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 ion) the applica
f3d0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
f3e0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
f3f0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a ementation for.*
f400: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
f410: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
f420: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 os_end(). An ap
f430: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
f440: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ed.** implementa
f450: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
f460: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c os_init() or sql
f470: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
f480: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 must return [SQ
f490: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
f4a0: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 ess and some oth
f4b0: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 er [error code]
f4c0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e upon.** failure.
f4d0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 initialize(void)
f4f0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 ;.int sqlite3_sh
f500: 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e utdown(void);.in
f510: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
f520: 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c t(void);.int sql
f530: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 ite3_os_end(void
f540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
f550: 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 EF: Configuring
f560: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 The SQLite Libra
f570: 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ry.**.** The sql
f580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e ite3_config() in
f590: 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
f5a0: 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 to make global c
f5b0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
f5c0: 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 changes to SQLit
f5d0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 e in order to tu
f5e0: 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 ne SQLite to the
f5f0: 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 specific needs
f600: 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 of.** the applic
f610: 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 ation. The defa
f620: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
f630: 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 n is recommended
f640: 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 for most.** app
f650: 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f lications and so
f660: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
f670: 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 usually not nec
f680: 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a essary. It is.*
f690: 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 * provided to su
f6a0: 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 pport rare appli
f6b0: 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 cations with unu
f6c0: 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a sual needs..**.*
f6d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f * The sqlite3_co
f6e0: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
f6f0: 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 is not threadsa
f700: 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 fe. The applica
f710: 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 tion.** must ins
f720: 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 ure that no othe
f730: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
f740: 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 ces are invoked
f750: 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 by other.** thre
f760: 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 ads while sqlite
f770: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 3_config() is ru
f780: 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d nning. Furtherm
f790: 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e ore, sqlite3_con
f7a0: 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c fig().** may onl
f7b0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 y be invoked pri
f7c0: 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e or to library in
f7d0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 itialization usi
f7e0: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 ng.** [sqlite3_i
f7f0: 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 nitialize()] or
f800: 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 after shutdown b
f810: 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 y [sqlite3_shutd
f820: 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 own()]..** ^If s
f830: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
f840: 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 is called after
f850: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c [sqlite3_initial
f860: 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 ize()] and befor
f870: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 e.** [sqlite3_sh
f880: 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 utdown()] then i
f890: 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 t will return SQ
f8a0: 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 LITE_MISUSE..**
f8b0: 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 Note, however, t
f8c0: 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e hat ^sqlite3_con
f8d0: 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c fig() can be cal
f8e0: 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 led as part of t
f8f0: 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
f900: 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 tion of an appli
f910: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b cation-defined [
f920: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
f930: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 )]..**.** The fi
f940: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
f950: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f960: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a is an integer.*
f970: 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e * [configuration
f980: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 option] that de
f990: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 termines.** what
f9a0: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c property of SQL
f9b0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e ite is to be con
f9c0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 figured. Subseq
f9d0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a uent arguments.*
f9e0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 * vary depending
f9f0: 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 on the [configu
fa00: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a ration option].*
fa10: 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 * in the first a
fa20: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
fa30: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 When a configura
fa40: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 tion option is s
fa50: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 et, sqlite3_conf
fa60: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 ig() returns [SQ
fa70: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 LITE_OK]..** ^If
fa80: 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 the option is u
fa90: 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 nknown or SQLite
faa0: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 is unable to se
fab0: 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 t the option.**
fac0: 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
fad0: 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d e returns a non-
fae0: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
faf0: 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 ]..*/.int sqlite
fb00: 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 3_config(int, ..
fb10: 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
fb20: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 REF: Configure d
fb30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
fb40: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ons.**.** The sq
fb50: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
fb60: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 ) interface is u
fb70: 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 sed to make conf
fb80: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 iguration.** cha
fb90: 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 nges to a [datab
fba0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e ase connection].
fbb0: 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 The interface
fbc0: 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a is similar to.**
fbd0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
fbe0: 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 ()] except that
fbf0: 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c the changes appl
fc00: 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a y to a single.**
fc10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
fc20: 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 ction] (specifie
fc30: 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 d in the first a
fc40: 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 rgument)..**.**
fc50: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
fc60: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 ent to sqlite3_d
fc70: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e b_config(D,V,...
fc80: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 ) is the.** [SQ
fc90: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
fca0: 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 OKASIDE | config
fcb0: 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 uration verb] -
fcc0: 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 an integer code
fcd0: 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 .** that indicat
fce0: 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f es what aspect o
fcf0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
fd00: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 connection] is b
fd10: 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e eing configured.
fd20: 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 .** Subsequent a
fd30: 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 rguments vary de
fd40: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
fd50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 onfiguration ver
fd60: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 b..**.** ^Calls
fd70: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
fd80: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 nfig() return SQ
fd90: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f LITE_OK if and o
fda0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 nly if.** the ca
fdb0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 ll is considered
fdc0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a successful..*/.
fdd0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 int sqlite3_db_c
fde0: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 onfig(sqlite3*,
fdf0: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f int op, ...);../
fe00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
fe10: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
fe20: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 Routines.**.**
fe30: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
fe40: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
fe50: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
fe60: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a between SQLite.
fe70: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c ** and low-level
fe80: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
fe90: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a on routines..**.
fea0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
feb0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f s used in only o
fec0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 ne place in the
fed0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
fee0: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 ..** A pointer t
fef0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
ff00: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
ff10: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a the argument to.
ff20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
ff30: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 ig()] when the c
ff40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
ff50: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 ion is.** [SQLIT
ff60: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
ff70: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
ff80: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 IG_GETMALLOC].
ff90: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 .** By creating
ffa0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
ffb0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e his object.** an
ffc0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 d passing it to
ffd0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
ffe0: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
fff0: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 MALLOC]).** duri
10000 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
10010 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
10020 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
10030 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
10040 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10050 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 subsystem for S
10060 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
10070 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 all of its.** d
10080 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 ynamic memory ne
10090 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 eds..**.** Note
100a0 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 that SQLite come
100b0 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b s with several [
100c0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
100d0 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 allocators].** t
100e0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c hat are perfectl
100f0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 y adequate for t
10100 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 he overwhelming
10110 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c majority of appl
10120 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 ications.** and
10130 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 that this object
10140 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 is only useful
10150 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 to a tiny minori
10160 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
10170 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 ns.** with speci
10180 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c alized memory al
10190 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 location require
101a0 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a ments. This obj
101b0 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 ect is.** also u
101c0 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
101d0 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 ng of SQLite in
101e0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 order to specify
101f0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
10200 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
10210 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 tor that simulat
10220 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 es memory out-of
10230 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f -memory conditio
10240 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 ns in.** order t
10250 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 o verify that SQ
10260 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 Lite recovers gr
10270 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 acefully from su
10280 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 ch.** conditions
10290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c ..**.** The xMal
102a0 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 loc, xRealloc, a
102b0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 nd xFree methods
102c0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 must work like
102d0 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c the.** malloc(),
102e0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 realloc() and f
102f0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 ree() functions
10300 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
10310 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
10320 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 ^SQLite guarante
10330 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f es that the seco
10340 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
10350 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c * xRealloc is al
10360 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 ways a value ret
10370 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 urned by a prior
10380 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 call to xRoundu
10390 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 p..**.** xSize s
103a0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 hould return the
103b0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 allocated size
103c0 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f of a memory allo
103d0 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f cation.** previo
103e0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
103f0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 om xMalloc or xR
10400 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c ealloc. The all
10410 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 ocated size.** i
10420 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 s always at leas
10430 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 t as big as the
10440 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 requested size b
10450 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 ut may be larger
10460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 ..**.** The xRou
10470 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 ndup method retu
10480 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 rns what would b
10490 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 e the allocated
104a0 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d size of.** a mem
104b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 ory allocation g
104c0 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 iven a particula
104d0 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 r requested size
104e0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a . Most memory.*
104f0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 * allocators rou
10500 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c nd up memory all
10510 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 ocations at leas
10520 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 t to the next mu
10530 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 ltiple.** of 8.
10540 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 Some allocators
10550 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c round up to a l
10560 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f arger multiple o
10570 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 r to a power of
10580 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 2..** Every memo
10590 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
105a0 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 quest coming in
105b0 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 through [sqlite3
105c0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 _malloc()].** or
105d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
105e0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 c()] first calls
105f0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 xRoundup. If x
10600 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 Roundup returns
10610 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 0, .** that caus
10620 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e es the correspon
10630 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ding memory allo
10640 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a cation to fail..
10650 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 **.** The xInit
10660 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a method initializ
10670 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
10680 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 locator. For ex
10690 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 ample,.** it mig
106a0 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 ht allocate any
106b0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 require mutexes
106c0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e or initialize in
106d0 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 ternal data.** s
106e0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 tructures. The
106f0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
10700 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 is invoked (ind
10710 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b irectly) by.** [
10720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
10730 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 ()] and should d
10740 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 eallocate any re
10750 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 sources acquired
10760 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 .** by xInit. T
10770 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e he pAppData poin
10780 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 ter is used as t
10790 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
107a0 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e r to.** xInit an
107b0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a d xShutdown..**.
107c0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 ** SQLite holds
107d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 the [SQLITE_MUTE
107e0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d X_STATIC_MASTER]
107f0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 mutex when it i
10800 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 nvokes.** the xI
10810 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 nit method, so t
10820 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
10830 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 need not be thre
10840 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 adsafe. The.**
10850 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
10860 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 is only called
10870 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 from [sqlite3_sh
10880 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 utdown()] so it
10890 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 does.** not need
108a0 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 to be threadsaf
108b0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 e either. For a
108c0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 ll other methods
108d0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 , SQLite.** hold
108e0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
108f0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 TEX_STATIC_MEM]
10900 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 mutex as long as
10910 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
10920 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
10930 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 ] configuration
10940 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 option is turned
10950 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 on (which.** it
10960 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 is by default)
10970 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f and so the metho
10980 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ds are automatic
10990 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e ally serialized.
109a0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 .** However, if
109b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
109c0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 EMSTATUS] is dis
109d0 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 abled, then the
109e0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 other.** methods
109f0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
10a00 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 afe or else make
10a10 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e their own arran
10a20 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 gements for.** s
10a30 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a erialization..**
10a40 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
10a50 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e never invoke xIn
10a60 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f it() more than o
10a70 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 nce without an i
10a80 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 ntervening.** ca
10a90 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 ll to xShutdown(
10aa0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 )..*/.typedef st
10ab0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
10ac0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
10ad0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 _mem_methods;.st
10ae0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
10af0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 _methods {. voi
10b00 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e d *(*xMalloc)(in
10b10 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d t); /* M
10b20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
10b30 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
10b40 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 oid (*xFree)(voi
10b50 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a d*); /*
10b60 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c Free a prior al
10b70 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f location */. vo
10b80 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 id *(*xRealloc)(
10b90 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 void*,int); /*
10ba0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 Resize an alloca
10bb0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a tion */. int (*
10bc0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 xSize)(void*);
10bd0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 /* Retu
10be0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 rn the size of a
10bf0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a n allocation */.
10c00 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 int (*xRoundup
10c10 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
10c20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 /* Round up req
10c30 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c uest size to all
10c40 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a ocation size */.
10c50 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 int (*xInit)(v
10c60 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
10c70 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 /* Initialize t
10c80 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
10c90 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a tor */. void (*
10ca0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a xShutdown)(void*
10cb0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 ); /* Deini
10cc0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
10cd0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
10ce0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 void *pAppData
10cf0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
10d00 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 /* Argument to
10d10 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 xInit() and xShu
10d20 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f tdown() */.};../
10d30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
10d40 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
10d50 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
10d60 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e : {configuration
10d70 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 option}.**.** T
10d80 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
10d90 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 re the available
10da0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 integer configu
10db0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 ration options t
10dc0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 hat.** can be pa
10dd0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
10de0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
10df0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
10e00 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
10e10 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
10e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
10e30 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
10e40 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
10e50 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
10e60 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
10e70 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
10e80 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
10e90 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
10ea0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
10eb0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
10ec0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
10ed0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
10ee0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
10ef0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
10f00 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
10f10 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
10f20 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
10f30 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
10f40 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
10f50 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
10f60 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
10f70 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
10f80 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
10f90 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
10fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
10fb0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 LETHREAD]] <dt>S
10fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
10fd0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a GLETHREAD</dt>.*
10fe0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
10ff0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
11000 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
11010 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
11020 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
11030 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c g mode] to Singl
11040 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 e-thread. In ot
11050 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 her words, it di
11060 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 sables.** all mu
11070 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 texing and puts
11080 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f SQLite into a mo
11090 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 de where it can
110a0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 only be used.**
110b0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 by a single thre
110c0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 ad. ^If SQLite
110d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
110e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
110f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
11100 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
11110 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
11120 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
11130 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
11140 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 e to change the
11150 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
11160 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c from its defaul
11170 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 t.** value of Si
11180 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 ngle-thread and
11190 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 so [sqlite3_conf
111a0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
111b0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 n .** [SQLITE_ER
111c0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
111d0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
111e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
111f0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 AD.** configurat
11200 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
11210 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
11220 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
11230 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AD]] <dt>SQLITE_
11240 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
11250 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
11260 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
11270 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
11280 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
11290 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
112a0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
112b0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 to Multi-thread
112c0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
112d0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a s, it disables.*
112e0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 * mutexing on [d
112f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11300 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
11310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
11320 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ects..** The app
11330 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 lication is resp
11340 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 onsible for seri
11350 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 alizing access t
11360 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 o.** [database c
11370 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
11380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
11390 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 ents]. But othe
113a0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 r mutexes.** are
113b0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 enabled so that
113c0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
113d0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 safe to use in a
113e0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a multi-threaded.
113f0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 ** environment a
11400 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f s long as no two
11410 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 threads attempt
11420 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
11430 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
11440 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 nnection] at the
11450 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 same time. ^If
11460 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
11470 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
11480 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
11490 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
114a0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
114b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
114c0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
114d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
114e0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 the Multi-thread
114f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
11500 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
11510 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
11520 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
11530 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
11540 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c with the.** SQL
11550 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
11560 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 THREAD configura
11570 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
11580 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
11590 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
115a0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f ED]] <dt>SQLITE_
115b0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
115c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
115d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
115e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
115f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
11600 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
11610 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
11620 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 to Serialized. I
11630 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
11640 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c his option enabl
11650 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 es.** all mutexe
11660 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 s including the
11670 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 recursive.** mut
11680 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 exes on [databas
11690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
116a0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
116b0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
116c0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 ** In this mode
116d0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 (which is the de
116e0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 fault when SQLit
116f0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
11700 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 th.** [SQLITE_TH
11710 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 READSAFE=1]) the
11720 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
11730 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 will itself seri
11740 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 alize access.**
11750 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e to [database con
11760 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 nections] and [p
11770 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
11780 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a ts] so that the.
11790 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 ** application i
117a0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 s free to use th
117b0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
117c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 connection] or
117d0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 the.** same [pre
117e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
117f0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 in different th
11800 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
11810 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 e time..** ^If S
11820 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
11830 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
11840 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
11850 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
11860 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
11870 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
11880 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
11890 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 ssible to set th
118a0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e Serialized [th
118b0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e reading mode] an
118c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
118d0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
118e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
118f0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
11900 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
11910 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
11920 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 D configuration
11930 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
11940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
11950 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e IG_MALLOC]] <dt>
11960 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
11970 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
11980 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
11990 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
119a0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
119b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
119c0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 .** instance of
119d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
119e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
119f0 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 ure. The argume
11a00 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
11a10 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
11a20 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
11a30 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
11a40 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
11a50 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
11a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11a70 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
11a80 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e into SQLite.)^ ^
11a90 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 SQLite makes.**
11aa0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
11ab0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 copy of the cont
11ac0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ent of the [sqli
11ad0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
11ae0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 structure.** be
11af0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 fore the [sqlite
11b00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 3_config()] call
11b10 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a returns.</dd>.*
11b20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
11b30 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d NFIG_GETMALLOC]]
11b40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
11b50 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 IG_GETMALLOC</dt
11b60 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
11b70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
11b80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
11b90 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
11ba0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
11bb0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
11bc0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
11bd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
11be0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
11bf0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
11c00 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
11c10 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
11c20 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 y defined memory
11c30 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
11c40 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 ines.)^.** This
11c50 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
11c60 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
11c70 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 he default memor
11c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
11c90 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
11ca0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d wrapper that sim
11cb0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 ulations memory
11cc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 allocation failu
11cd0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 re or.** tracks
11ce0 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f memory usage, fo
11cf0 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e r example. </dd>
11d00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
11d10 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
11d20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
11d30 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f NFIG_MEMSTATUS</
11d40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
11d50 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 s option takes s
11d60 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
11d70 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 f type int, inte
11d80 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a rpreted as a .**
11d90 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 boolean, which
11da0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
11db0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 les the collecti
11dc0 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c on of memory all
11dd0 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 ocation .** stat
11de0 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d istics. ^(When m
11df0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11e00 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
11e10 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a disabled, the .*
11e20 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 * following SQLi
11e30 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 te interfaces be
11e40 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 come non-operati
11e50 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a onal:.** <ul>.
11e60 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
11e70 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
11e80 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
11e90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
11ea0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c water()].** <l
11eb0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 i> [sqlite3_soft
11ec0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d _heap_limit64()]
11ed0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
11ee0 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a te3_status()].**
11ef0 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d </ul>)^.** ^M
11f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
11f10 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
11f20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
11f30 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 lt unless SQLite
11f40 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
11f50 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 with [SQLITE_DEF
11f60 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d AULT_MEMSTATUS]=
11f70 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 0 in which case
11f80 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
11f90 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
11fa0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
11fb0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 default..** </dd
11fc0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
11fd0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
11fe0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
11ff0 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
12000 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
12010 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 ption specifies
12020 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 a static memory
12030 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 buffer that SQLi
12040 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a te can use for.*
12050 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 * scratch memory
12060 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 . There are thr
12070 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 ee arguments: A
12080 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 pointer an 8-by
12090 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 te.** aligned me
120a0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d mory buffer from
120b0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 which the scrat
120c0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 ch allocations w
120d0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c ill be.** drawn,
120e0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
120f0 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 h scratch alloca
12100 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e tion (sz),.** an
12110 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d the maximum nu
12120 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 mber of scratch
12130 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e allocations (N).
12140 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 The sz.** argu
12150 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d ment must be a m
12160 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a ultiple of 16..*
12170 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
12180 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 ment must be a p
12190 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 ointer to an 8-b
121a0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 yte aligned buff
121b0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 er.** of at leas
121c0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 t sz*N bytes of
121d0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 memory..** ^SQLi
121e0 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d te will use no m
121f0 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 ore than two scr
12200 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 atch buffers per
12210 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 thread. So.**
12220 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 N should be set
12230 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 to twice the exp
12240 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 ected maximum nu
12250 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e mber of threads.
12260 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
12270 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 never require a
12280 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 scratch buffer
12290 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 that is more tha
122a0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 n 6.** times the
122b0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 database page s
122c0 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 ize. ^If SQLite
122d0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 needs needs addi
122e0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 tional.** scratc
122f0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 h memory beyond
12300 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
12310 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 by this configu
12320 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 ration option, t
12330 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hen .** [sqlite3
12340 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 _malloc()] will
12350 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
12360 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 n the memory nee
12370 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ded.</dd>.**.**
12380 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12390 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e PAGECACHE]] <dt>
123a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
123b0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 GECACHE</dt>.**
123c0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
123d0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 n specifies a st
123e0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 atic memory buff
123f0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 er that SQLite c
12400 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 an use for.** th
12410 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
12420 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 cache with the d
12430 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 efault page cach
12440 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
12450 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 . .** This conf
12460 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 iguration should
12470 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 not be used if
12480 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
12490 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 efine page.** ca
124a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
124b0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 on is loaded usi
124c0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f ng the SQLITE_CO
124d0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 NFIG_PCACHE2 opt
124e0 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 ion..** There ar
124f0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
12500 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
12510 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 : A pointer to 8
12520 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a -byte aligned.**
12530 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a memory, the siz
12540 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 e of each page b
12550 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 uffer (sz), and
12560 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 the number of pa
12570 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 ges (N)..** The
12580 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 sz argument shou
12590 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f ld be the size o
125a0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 f the largest da
125b0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 tabase page.** (
125c0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 a power of two b
125d0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 etween 512 and 3
125e0 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 2768) plus a lit
125f0 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 tle extra for ea
12600 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 ch.** page heade
12610 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 r. ^The page he
12620 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 ader size is 20
12630 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 to 40 bytes depe
12640 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 nding on.** the
12650 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 host architectur
12660 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c e. ^It is harml
12670 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 ess, apart from
12680 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 the wasted memor
12690 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a y,.** to make sz
126a0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 a little too la
126b0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a rge. The first.
126c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
126d0 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 ld point to an a
126e0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 llocation of at
126f0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
12700 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e of memory..** ^
12710 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
12720 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 the memory provi
12730 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 ded by the first
12740 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 argument to sat
12750 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f isfy its.** memo
12760 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 ry needs for the
12770 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 first N pages t
12780 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 hat it adds to c
12790 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 ache. ^If addit
127a0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 ional.** page ca
127b0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 che memory is ne
127c0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 eded beyond what
127d0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 is provided by
127e0 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 this option, the
127f0 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 n.** SQLite goes
12800 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c to [sqlite3_mal
12810 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 loc()] for the a
12820 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 dditional storag
12830 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 e space..** The
12840 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 pointer in the f
12850 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 irst argument mu
12860 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 st.** be aligned
12870 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f to an 8-byte bo
12880 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 undary or subseq
12890 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 uent behavior of
128a0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 SQLite.** will
128b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 be undefined.</d
128c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
128d0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 E_CONFIG_HEAP]]
128e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
128f0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c G_HEAP</dt>.** <
12900 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
12910 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
12920 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
12930 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 r that SQLite wi
12940 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c ll use.** for al
12950 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 l of its dynamic
12960 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12970 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 on needs beyond
12980 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a those provided.*
12990 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 * for by [SQLITE
129a0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
129b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e and [SQLITE_CON
129c0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
129d0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 ** There are thr
129e0 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e ee arguments: An
129f0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
12a00 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
12a10 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 emory,.** the nu
12a20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
12a30 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 the memory buff
12a40 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 er, and the mini
12a50 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
12a60 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ize..** ^If the
12a70 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
12a80 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
12a90 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e r) is NULL, then
12aa0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a SQLite reverts.
12ab0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 ** to using its
12ac0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
12ad0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 llocator (the sy
12ae0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d stem malloc() im
12af0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a plementation),.*
12b00 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 * undoing any pr
12b10 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ior invocation o
12b20 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
12b30 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 _MALLOC]. ^If t
12b40 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 he.** memory poi
12b50 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
12b60 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c and either [SQL
12b70 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
12b80 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 S3] or.** [SQLIT
12b90 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 E_ENABLE_MEMSYS5
12ba0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 ] are defined, t
12bb0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 hen the alternat
12bc0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ive memory.** al
12bd0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 locator is engag
12be0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c ed to handle all
12bf0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f of SQLites memo
12c00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
12c10 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 eds..** The firs
12c20 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
12c30 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d emory pointer) m
12c40 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
12c50 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 o an 8-byte.** b
12c60 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 oundary or subse
12c70 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f quent behavior o
12c80 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 f SQLite will be
12c90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
12ca0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
12cb0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 ation size is ca
12cc0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 pped at 2**12. R
12cd0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 easonable values
12ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 .** for the mini
12cf0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
12d00 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 ize are 2**5 thr
12d10 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a ough 2**8.</dd>.
12d20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
12d30 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 ONFIG_MUTEX]] <d
12d40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12d50 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
12d60 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
12d70 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
12d80 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
12d90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
12da0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
12db0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
12dc0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
12dd0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 ucture. The arg
12de0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a ument specifies.
12df0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c ** alternative l
12e00 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 ow-level mutex r
12e10 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
12e20 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 ed in place.** t
12e30 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 he mutex routine
12e40 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
12e50 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ite.)^ ^SQLite
12e60 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
12e70 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f the.** content o
12e80 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
12e90 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
12ea0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 ructure before t
12eb0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 he call to.** [s
12ec0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
12ed0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 returns. ^If SQ
12ee0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
12ef0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
12f00 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
12f10 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
12f20 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
12f30 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
12f40 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
12f50 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
12f60 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
12f70 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
12f80 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
12f90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
12fa0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
12fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
12fc0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
12fd0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
12fe0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
12ff0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
13000 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13010 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 GETMUTEX]] <dt>S
13020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
13030 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
13040 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
13050 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
13060 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
13070 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
13080 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 n.** instance of
13090 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
130a0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
130b0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 ucture. The.**
130c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d [sqlite3_mutex_m
130d0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
130e0 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
130f0 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
13100 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 y defined mutex
13110 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 routines.)^.** T
13120 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 his option can b
13130 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f e used to overlo
13140 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d ad the default m
13150 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a utex allocation.
13160 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 ** routines with
13170 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 a wrapper used
13180 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 to track mutex u
13190 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d sage for perform
131a0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e ance.** profilin
131b0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f g or testing, fo
131c0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 r example. ^If
131d0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
131e0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
131f0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
13200 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
13210 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
13220 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
13230 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 en.** the entire
13240 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 mutexing subsys
13250 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 tem is omitted f
13260 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e rom the build an
13270 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f d hence calls to
13280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
13290 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 fig()] with the
132a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
132b0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 TMUTEX configura
132c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
132d0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
132e0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
132f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
13300 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
13310 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13320 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 FIG_LOOKASIDE</d
13330 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 t>.** <dd> ^(Thi
13340 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 s option takes t
13350 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 wo arguments tha
13360 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 t determine the
13370 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 default.** memor
13380 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 y allocation for
13390 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d the lookaside m
133a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
133b0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 on each.** [data
133c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
133d0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 . The first arg
133e0 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
133f0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f size of each loo
13400 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c kaside buffer sl
13410 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ot and the secon
13420 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
13430 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f of.** slots allo
13440 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 cated to each da
13450 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
13460 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 n.)^ ^(This opt
13470 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
13480 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c <i>default</i> l
13490 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 ookaside size. T
134a0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e he [SQLITE_DBCON
134b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a FIG_LOOKASIDE].*
134c0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 * verb to [sqlit
134d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
134e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
134f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
13500 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 ide.** configura
13510 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 tion on individu
13520 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 al connections.)
13530 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
13540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
13550 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
13560 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
13570 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 2</dt>.** <dd> ^
13580 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b (This option tak
13590 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
135a0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 ment which is a
135b0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e pointer to.** an
135c0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
135d0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
135e0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 t. This object
135f0 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e specifies the in
13600 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 terface.** to a
13610 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 custom page cach
13620 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
13630 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b .)^ ^SQLite mak
13640 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
13650 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 .** object and u
13660 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 ses it for page
13670 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c cache memory all
13680 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a ocations.</dd>.*
13690 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
136a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d NFIG_GETPCACHE2]
136b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
136c0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f FIG_GETPCACHE2</
136d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
136e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
136f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
13700 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
13710 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
13720 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
13730 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 thods2] object.
13740 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f SQLite copies o
13750 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a f the current.**
13760 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
13770 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 ementation into
13780 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c that object.)^ <
13790 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
137a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d ITE_CONFIG_LOG]]
137b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
137c0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c IG_LOG</dt>.** <
137d0 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 dd> The SQLITE_C
137e0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e ONFIG_LOG option
137f0 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 is used to conf
13800 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 igure the SQLite
13810 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f .** global [erro
13820 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 r log]..** (^The
13830 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
13840 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 OG option takes
13850 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 two arguments: a
13860 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a pointer to a.**
13870 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
13880 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 call signature
13890 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a of void(*)(void*
138a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
138b0 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 ), .** and a poi
138c0 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 nter to void. ^I
138d0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 f the function p
138e0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
138f0 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 LL, it is.** inv
13900 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oked by [sqlite3
13910 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 _log()] to proce
13920 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 ss each logging
13930 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a event. ^If the.
13940 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e ** function poin
13950 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ter is NULL, the
13960 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
13970 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d interface becom
13980 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e es a no-op..** ^
13990 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 The void pointer
139a0 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 that is the sec
139b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
139c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
139d0 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 G is.** passed t
139e0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 hrough as the fi
139f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
13a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
13a10 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a -defined logger.
13a20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e ** function when
13a30 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 ever that functi
13a40 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 on is invoked.
13a50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
13a60 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
13a70 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 logger function
13a80 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
13a90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
13aa0 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f to the correspo
13ab0 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 nding.** [sqlite
13ac0 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 3_log()] call an
13ad0 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f d is intended to
13ae0 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f be a [result co
13af0 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 de] or an.** [ex
13b00 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
13b10 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 de]. ^The third
13b20 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 parameter passe
13b30 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 d to the logger
13b40 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 is.** log messag
13b50 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 e after formatti
13b60 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f ng via [sqlite3_
13b70 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 snprintf()]..**
13b80 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 The SQLite loggi
13b90 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ng interface is
13ba0 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 not reentrant; t
13bb0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
13bc0 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 on.** supplied b
13bd0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
13be0 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b n must not invok
13bf0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 e any SQLite int
13c00 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 erface..** In a
13c10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 multi-threaded a
13c20 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 pplication, the
13c30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
13c40 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 ned logger.** fu
13c50 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 nction must be t
13c60 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e hreadsafe. </dd>
13c70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
13c80 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 CONFIG_URI]] <dt
13c90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 >SQLITE_CONFIG_U
13ca0 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 RI.** <dd>^(This
13cb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
13cc0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
13cd0 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 of type int. If
13ce0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a non-zero, then.*
13cf0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 * URI handling i
13d00 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c s globally enabl
13d10 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d ed. If the param
13d20 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 eter is zero, th
13d30 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a en URI handling.
13d40 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 ** is globally d
13d50 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 isabled.)^ ^If U
13d60 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
13d70 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c lobally enabled,
13d80 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a all filenames.*
13d90 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c * passed to [sql
13da0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
13db0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
13dc0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
13dd0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 16()] or.** spec
13de0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 ified as part of
13df0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e [ATTACH] comman
13e00 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 ds are interpret
13e10 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 ed as URIs, rega
13e20 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 rdless.** of whe
13e30 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
13e40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 [SQLITE_OPEN_URI
13e50 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 ] flag is set wh
13e60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a en the database.
13e70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
13e80 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 opened. ^If it
13e90 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 is globally disa
13ea0 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 bled, filenames
13eb0 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 are.** only inte
13ec0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 rpreted as URIs
13ed0 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 if the SQLITE_OP
13ee0 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 EN_URI flag is s
13ef0 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 et when the.** d
13f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
13f10 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 on is opened. ^(
13f20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 By default, URI
13f30 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
13f40 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 ally.** disabled
13f50 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 . The default va
13f60 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 lue may be chang
13f70 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 ed by compiling
13f80 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
13f90 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d ITE_USE_URI] sym
13fa0 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a bol defined.)^.*
13fb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
13fc0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
13fd0 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 DEX_SCAN]] <dt>S
13fe0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
13ff0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
14000 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 .** <dd>^This op
14010 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
14020 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 gle integer argu
14030 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e ment which is in
14040 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 terpreted as.**
14050 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 a boolean in ord
14060 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 er to enable or
14070 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 disable the use
14080 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 of covering indi
14090 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 ces for.** full
140a0 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 table scans in t
140b0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a he query optimiz
140c0 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c er. ^The defaul
140d0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 t setting is det
140e0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 ermined.** by th
140f0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f e [SQLITE_ALLOW_
14100 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
14110 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d CAN] compile-tim
14120 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 e option, or is
14130 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 "on".** if that
14140 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
14150 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ion is omitted..
14160 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 ** The ability t
14170 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 o disable the us
14180 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e e of covering in
14190 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 dices for full t
141a0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 able scans.** is
141b0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e because some in
141c0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 correctly coded
141d0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 legacy applicati
141e0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e ons might malfun
141f0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 ction.** when th
14200 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 e optimization i
14210 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 s enabled. Prov
14220 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 iding the abilit
14230 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 y to.** disable
14240 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e the optimization
14250 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 allows the olde
14260 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 r, buggy applica
14270 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 tion code to wor
14280 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 k.** without cha
14290 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 nge even with ne
142a0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
142b0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b SQLite..**.** [[
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
142d0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f ACHE]] [[SQLITE_
142e0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
142f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
14300 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 _CONFIG_PCACHE a
14310 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 nd SQLITE_CONFIG
14320 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 _GETPCACHE.** <d
14330 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 d> These options
14340 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e are obsolete an
14350 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 d should not be
14360 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 used by new code
14370 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 ..** They are re
14380 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 tained for backw
14390 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
143a0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e ty but are now n
143b0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a o-ops..** </dd>.
143c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
143d0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a ONFIG_SQLLOG]].*
143e0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
143f0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 FIG_SQLLOG.** <d
14400 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 d>This option is
14410 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
14420 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d if sqlite is com
14430 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
14440 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
14450 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f _SQLLOG] pre-pro
14460 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 cessor macro def
14470 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 ined. The first
14480 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a argument should.
14490 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 ** be a pointer
144a0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 to a function of
144b0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f type void(*)(vo
144c0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e id*,sqlite3*,con
144d0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a st char*, int)..
144e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 ** The second sh
144f0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 ould be of type
14500 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c (void*). The cal
14510 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
14520 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a by the library.
14530 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 ** in three sepa
14540 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 rate circumstanc
14550 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 es, identified b
14560 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 y the value pass
14570 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 ed as the.** fou
14580 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 rth parameter. I
14590 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
145a0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 ameter is 0, the
145b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
145c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 onnection.** pas
145d0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
145e0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a d argument has j
145f0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e ust been opened.
14600 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
14610 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ent.** points to
14620 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 a buffer contai
14630 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 ning the name of
14640 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
14650 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a se file. If the.
14660 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 ** fourth parame
14670 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 ter is 1, then t
14680 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
14690 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 that the third
146a0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 parameter.** poi
146b0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 nts to has just
146c0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f been executed. O
146d0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 r, if the fourth
146e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c parameter is 2,
146f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e then.** the con
14700 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 nection being pa
14710 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ssed as the seco
14720 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
14730 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 being closed. Th
14740 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
14750 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e eter is passed N
14760 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 ULL In this case
14770 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 . An example of
14780 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 using this.** c
14790 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
147a0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 ion can be seen
147b0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c in the "test_sql
147c0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 log.c" source fi
147d0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e le in.** the can
147e0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f onical SQLite so
147f0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a urce tree.</dd>.
14800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14810 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d ONFIG_MMAP_SIZE]
14820 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
14830 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
14840 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f .** <dd>^SQLITE_
14850 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
14860 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 takes two 64-bi
14870 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 t integer (sqlit
14880 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 e3_int64) values
14890 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 .** that are the
148a0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 default mmap si
148b0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 ze limit (the de
148c0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f fault setting fo
148d0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 r.** [PRAGMA mma
148e0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 p_size]) and the
148f0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 maximum allowed
14900 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 mmap size limit
14910 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
14920 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 t setting can be
14930 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 overridden by e
14940 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
14950 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a nection using.**
14960 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 either the [PRA
14970 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 GMA mmap_size] c
14980 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 ommand, or by us
14990 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ing the.** [SQLI
149a0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
149b0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c ZE] file control
149c0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d . ^(The maximum
149d0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
149e0 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 ze.** cannot be
149f0 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 changed at run-t
14a00 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 ime. Nor may th
14a10 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 e maximum allowe
14a20 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 d mmap size.** e
14a30 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c xceed the compil
14a40 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d e-time maximum m
14a50 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 map size set by
14a60 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d the.** [SQLITE_M
14a70 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f AX_MMAP_SIZE] co
14a80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
14a90 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 n.)^.** ^If eith
14aa0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 er argument to t
14ab0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 his option is ne
14ac0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 gative, then tha
14ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a t argument is.**
14ae0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 changed to its
14af0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 compile-time def
14b00 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ault..**.** [[SQ
14b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
14b20 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 2_HEAPSIZE]].**
14b30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
14b40 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
14b50 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 .** <dd>^This op
14b60 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 tion is only ava
14b70 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 ilable if SQLite
14b80 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 is compiled for
14b90 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 Windows.** with
14ba0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e the [SQLITE_WIN
14bb0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 32_MALLOC] pre-p
14bc0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 rocessor macro d
14bd0 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 efined..** SQLIT
14be0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
14bf0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 EAPSIZE takes a
14c00 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 32-bit unsigned
14c10 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a integer value.**
14c20 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
14c30 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 the maximum size
14c40 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 of the created
14c50 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a heap..** </dl>.*
14c60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
14c70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
14c80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 READ 1 /* nil
14c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
14ca0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
14cb0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c READ 2 /* nil
14cc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14cd0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
14ce0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 IZED 3 /* ni
14cf0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
14d00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
14d10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 C 4 /* s
14d20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
14d30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
14d40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
14d50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a MALLOC 5 /*
14d60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 sqlite3_mem_met
14d70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 hods* */.#define
14d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
14d90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 CRATCH 6
14da0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
14db0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
14dc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
14dd0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 _PAGECACHE 7
14de0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
14df0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 sz, int N */.#de
14e00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
14e10 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 IG_HEAP
14e20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 8 /* void*, in
14e30 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e t nByte, int min
14e40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14e50 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
14e60 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f TUS 9 /* bo
14e70 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 olean */.#define
14e80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
14e90 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 UTEX 10
14ea0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 /* sqlite3_mutex
14eb0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
14ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
14ed0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 IG_GETMUTEX
14ee0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 11 /* sqlite3_m
14ef0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f utex_methods* */
14f00 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 ./* previously S
14f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 QLITE_CONFIG_CHU
14f20 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 NKALLOC 12 which
14f30 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 is now unused.
14f40 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */ .#define SQLI
14f50 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
14f60 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e IDE 13 /* in
14f70 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 t int */.#define
14f80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
14f90 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 CACHE 14
14fa0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 /* no-op */.#def
14fb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
14fc0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 G_GETPCACHE 1
14fd0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 5 /* no-op */.#
14fe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
14ff0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 NFIG_LOG
15000 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 16 /* xFunc,
15010 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 void* */.#define
15020 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 SQLITE_CONFIG_U
15030 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 RI 17
15040 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e /* int */.#defin
15050 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15060 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 PCACHE2 18
15070 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 /* sqlite3_pcac
15080 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a he_methods2* */.
15090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
150a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
150b0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 19 /* sqlite
150c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
150d0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
150e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
150f0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 RING_INDEX_SCAN
15100 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 20 /* int */.#d
15110 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
15120 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 FIG_SQLLOG
15130 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 21 /* xSqllog,
15140 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
15150 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15160 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 MMAP_SIZE 22
15170 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 /* sqlite3_int6
15180 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 4, sqlite3_int64
15190 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
151a0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
151b0 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 HEAPSIZE 23
151c0 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a /* int nByte *
151d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
151e0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e F: Database Conn
151f0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 ection Configura
15200 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a tion Options.**.
15210 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
15220 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c ts are the avail
15230 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e able integer con
15240 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
15250 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 ns that.** can b
15260 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
15270 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
15280 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
15290 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 db_config()] int
152a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 erface..**.** Ne
152b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 w configuration
152c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 options may be a
152d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
152e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 eleases of SQLit
152f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 e..** Existing c
15300 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
15310 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 ions might be di
15320 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 scontinued. App
15330 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
15340 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 uld check the re
15350 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b turn code from [
15360 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
15370 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
15380 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
15390 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 ll worked. ^The
153a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
153b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
153c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
153d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
153e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
153f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
15400 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
15410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
15420 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
15430 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 ** <dl>.** <dt>S
15440 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
15450 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a OOKASIDE</dt>.**
15460 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
15470 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 on takes three a
15480 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
15490 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
154a0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b ne the .** [look
154b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
154c0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 ocator] configur
154d0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 ation for the [d
154e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
154f0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 on]..** ^The fir
15500 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 st argument (the
15510 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
15520 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
15530 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a config()] is a.*
15540 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d * pointer to a m
15550 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 emory buffer to
15560 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 use for lookasid
15570 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 e memory..** ^Th
15580 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
15590 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 after the SQLIT
155a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
155b0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 SIDE verb.** may
155c0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 be NULL in whic
155d0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 h case SQLite wi
155e0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a ll allocate the.
155f0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ** lookaside buf
15600 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 fer itself using
15610 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
15620 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 ()]. ^The second
15630 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
15640 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 .** size of each
15650 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
15660 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 r slot. ^The th
15670 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
15680 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
15690 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a slots. The siz
156a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 e of the buffer
156b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
156c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 ument must be gr
156d0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 eater than.** or
156e0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 equal to the pr
156f0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 oduct of the sec
15700 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 ond and third ar
15710 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 guments. The bu
15720 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 ffer.** must be
15730 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
15740 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 byte boundary.
15750 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 ^If the second a
15760 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 rgument to.** SQ
15770 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
15780 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 OKASIDE is not a
15790 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 multiple of 8,
157a0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 it is internally
157b0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e .** rounded down
157c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 to the next sma
157d0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 ller multiple of
157e0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 8. ^(The looka
157f0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 side memory.** c
15800 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 onfiguration for
15810 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
15820 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 ection can only
15830 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 be changed when
15840 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 that.** connecti
15850 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e on is not curren
15860 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 tly using lookas
15870 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 ide memory, or i
15880 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a n other words.**
15890 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 when the "curre
158a0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e nt value" return
158b0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
158c0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 3_db_status](D,[
158d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
158e0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 OKASIDE],...) is
158f0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 zero..** Any at
15900 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 tempt to change
15910 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 the lookaside me
15920 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 mory configurati
15930 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 on when lookasid
15940 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 e.** memory is i
15950 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 n use leaves the
15960 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 configuration u
15970 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 nchanged and ret
15980 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 urns .** [SQLITE
15990 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a _BUSY].)^</dd>.*
159a0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
159b0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
159c0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 FKEY</dt>.** <dd
159d0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 > ^This option i
159e0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 s used to enable
159f0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 or disable the
15a00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a enforcement of.*
15a10 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 * [foreign key c
15a20 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 onstraints]. Th
15a30 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
15a40 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
15a50 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 uments..** The f
15a60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
15a70 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
15a80 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
15a90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
15aa0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
15ab0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 enable FK enfor
15ac0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 cement or negati
15ad0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 ve to leave FK e
15ae0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e nforcement.** un
15af0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 changed. The se
15b00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
15b10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
15b20 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
15b30 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
15b40 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
15b50 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b icate whether FK
15b60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 enforcement is
15b70 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c off or on.** fol
15b80 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
15b90 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
15ba0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 rameter may be a
15bb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 NULL pointer, i
15bc0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 n.** which case
15bd0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 the FK enforceme
15be0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f nt setting is no
15bf0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
15c00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
15c10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
15c20 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c _ENABLE_TRIGGER<
15c30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
15c40 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
15c50 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
15c60 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 isable [CREATE T
15c70 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
15c80 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f s]..** There sho
15c90 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
15ca0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
15cb0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
15cc0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
15cd0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
15ce0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 to disable trigg
15cf0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ers,.** positive
15d00 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 to enable trigg
15d10 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ers or negative
15d20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 to leave the set
15d30 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a ting unchanged..
15d40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
15d50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
15d60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
15d70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
15d80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
15d90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
15da0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 hether triggers
15db0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 are disabled or
15dc0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f enabled.** follo
15dd0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 wing this call.
15de0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
15df0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e meter may be a N
15e00 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a ULL pointer, in.
15e10 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 ** which case th
15e20 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e e trigger settin
15e30 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
15e40 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a d back. </dd>.**
15e50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 .** </dl>.*/.#de
15e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
15e70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
15e80 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 1001 /* vo
15e90 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 id* int int */.#
15ea0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
15eb0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
15ec0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 EY 1002 /*
15ed0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
15ee0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
15ef0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 FIG_ENABLE_TRIGG
15f00 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 ER 1003 /* int
15f10 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a int* */.../*.**
15f20 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c CAPI3REF: Enabl
15f30 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 e Or Disable Ext
15f40 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
15f50 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 es.**.** ^The sq
15f60 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 lite3_extended_r
15f70 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f esult_codes() ro
15f80 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 utine enables or
15f90 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a disables the.**
15fa0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
15fb0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 t codes] feature
15fc0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 of SQLite. ^The
15fd0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
15fe0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 .** codes are di
15ff0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c sabled by defaul
16000 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c t for historical
16010 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
16020 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 */.int sqlite3_e
16030 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
16040 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 odes(sqlite3*, i
16050 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a nt onoff);../*.*
16060 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 * CAPI3REF: Last
16070 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a Insert Rowid.**
16080 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 .** ^Each entry
16090 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 in most SQLite t
160a0 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f ables (except fo
160b0 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 r [WITHOUT ROWID
160c0 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 ] tables).** has
160d0 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 a unique 64-bit
160e0 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 signed.** integ
160f0 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 er key called th
16100 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 e [ROWID | "rowi
16110 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 d"]. ^The rowid
16120 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 is always availa
16130 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 ble.** as an und
16140 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e eclared column n
16150 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c amed ROWID, OID,
16160 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c or _ROWID_ as l
16170 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 ong as those.**
16180 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c names are not al
16190 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 so used by expli
161a0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 citly declared c
161b0 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 olumns. ^If.** t
161c0 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 he table has a c
161d0 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 olumn of type [I
161e0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b NTEGER PRIMARY K
161f0 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f EY] then that co
16200 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 lumn.** is anoth
16210 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 er alias for the
16220 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rowid..**.** ^T
16230 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f he sqlite3_last_
16240 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 insert_rowid(D)
16250 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
16260 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 s the [rowid] of
16270 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 the .** most re
16280 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 cent successful
16290 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 [INSERT] into a
162a0 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b rowid table or [
162b0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a virtual table].*
162c0 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f * on database co
162d0 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e nnection D..** ^
162e0 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 Inserts into [WI
162f0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 THOUT ROWID] tab
16300 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f les are not reco
16310 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 rded..** ^If no
16320 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
16330 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 RT]s into rowid
16340 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 tables.** have e
16350 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 ver occurred on
16360 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
16370 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 nection D, .** t
16380 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 hen sqlite3_last
16390 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 _insert_rowid(D)
163a0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a returns zero..*
163b0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e *.** ^(If an [IN
163c0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 SERT] occurs wit
163d0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 hin a trigger or
163e0 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 within a [virtu
163f0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 al table].** met
16400 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 hod, then this r
16410 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 outine will retu
16420 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f rn the [rowid] o
16430 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a f the inserted.*
16440 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 * row as long as
16450 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 the trigger or
16460 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 virtual table me
16470 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e thod is running.
16480 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 .** But once the
16490 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 trigger or virt
164a0 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 ual table method
164b0 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 ends, the value
164c0 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 returned .** by
164d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 this routine re
164e0 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 verts to what it
164f0 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 was before the
16500 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
16510 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 al.** table meth
16520 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a od began.)^.**.*
16530 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 * ^An [INSERT] t
16540 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f hat fails due to
16550 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 a constraint vi
16560 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 olation is not a
16570 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b .** successful [
16580 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 INSERT] and does
16590 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
165a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
165b0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e y this.** routin
165c0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 e. ^Thus INSERT
165d0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 OR FAIL, INSERT
165e0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 OR IGNORE, INSE
165f0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a RT OR ROLLBACK,.
16600 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 ** and INSERT OR
16610 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 ABORT make no c
16620 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 hanges to the re
16630 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
16640 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 is.** routine wh
16650 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 en their inserti
16660 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 on fails. ^(Whe
16670 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c n INSERT OR REPL
16680 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 ACE.** encounter
16690 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 s a constraint v
166a0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 iolation, it doe
166b0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 s not fail. The
166c0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 .** INSERT conti
166d0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 nues to completi
166e0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e on after deletin
166f0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 g rows that caus
16700 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 ed.** the constr
16710 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 aint problem so
16720 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 INSERT OR REPLAC
16730 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 E will always ch
16740 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 ange.** the retu
16750 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 rn value of this
16760 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a interface.)^.**
16770 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 .** ^For the pur
16780 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f poses of this ro
16790 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 utine, an [INSER
167a0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 T] is considered
167b0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 to.** be succes
167c0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 sful even if it
167d0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 is subsequently
167e0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a rolled back..**.
167f0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e ** This function
16800 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 is accessible t
16810 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 o SQL statements
16820 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 via the.** [las
16830 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
16840 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a SQL function]..
16850 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 **.** If a separ
16860 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f ate thread perfo
16870 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 rms a new [INSER
16880 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a T] on the same.*
16890 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
168a0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 ction while the
168b0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e [sqlite3_last_in
168c0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a sert_rowid()].**
168d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
168e0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 ning and thus ch
168f0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 anges the last i
16900 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a nsert [rowid],.*
16910 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 * then the value
16920 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
16930 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
16940 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a t_rowid()] is.**
16950 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 unpredictable a
16960 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 nd might not equ
16970 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c al either the ol
16980 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 d or the new.**
16990 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 last insert [row
169a0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f id]..*/.sqlite3_
169b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 int64 sqlite3_la
169c0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
169d0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a sqlite3*);../*.*
169e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e * CAPI3REF: Coun
169f0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 t The Number Of
16a00 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
16a10 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
16a20 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
16a30 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 umber of databas
16a40 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 e rows that were
16a50 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 changed.** or i
16a60 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 nserted or delet
16a70 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 ed by the most r
16a80 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
16a90 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a d SQL statement.
16aa0 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 ** on the [datab
16ab0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
16ac0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
16ad0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
16ae0 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e ..** ^(Only chan
16af0 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 ges that are dir
16b00 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 ectly specified
16b10 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c by the [INSERT],
16b20 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 [UPDATE],.** or
16b30 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
16b40 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e ent are counted.
16b50 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e Auxiliary chan
16b60 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a ges caused by.**
16b70 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f triggers or [fo
16b80 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e reign key action
16b90 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 s] are not count
16ba0 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a ed.)^ Use the.**
16bb0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
16bc0 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 changes()] funct
16bd0 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 ion to find the
16be0 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 total number of
16bf0 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 changes.** inclu
16c00 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 ding changes cau
16c10 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 sed by triggers
16c20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 and foreign key
16c30 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e actions..**.** ^
16c40 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 Changes to a vie
16c50 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c w that are simul
16c60 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 ated by an [INST
16c70 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a EAD OF trigger].
16c80 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 ** are not count
16c90 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 ed. Only real t
16ca0 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 able changes are
16cb0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 counted..**.**
16cc0 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 ^(A "row change"
16cd0 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 is a change to
16ce0 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 a single row of
16cf0 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a a single table.*
16d00 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 * caused by an I
16d10 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f NSERT, DELETE, o
16d20 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 r UPDATE stateme
16d30 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a nt. Rows that.*
16d40 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 * are changed as
16d50 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 side effects of
16d60 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
16d70 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
16d80 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 ,.** rollback, A
16d90 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c BORT processing,
16da0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f [DROP TABLE], o
16db0 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a r by any other.*
16dc0 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 * mechanisms do
16dd0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 not count as dir
16de0 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e ect row changes.
16df0 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 )^.**.** A "trig
16e00 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 ger context" is
16e10 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 a scope of execu
16e20 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 tion that begins
16e30 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 and.** ends wit
16e40 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 h the script of
16e50 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 a [CREATE TRIGGE
16e60 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a R | trigger]. .*
16e70 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 * Most SQL state
16e80 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 ments are.** eva
16e90 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f luated outside o
16ea0 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 f any trigger.
16eb0 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 This is the "top
16ec0 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 level".** trigg
16ed0 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 er context. If
16ee0 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 a trigger fires
16ef0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 from the top lev
16f00 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 el, a.** new tri
16f10 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 gger context is
16f20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 entered for the
16f30 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 duration of that
16f40 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e one.** trigger.
16f50 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 Subtriggers cr
16f60 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 eate subcontexts
16f70 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 for their durat
16f80 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c ion..**.** ^Call
16f90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 ing [sqlite3_exe
16fa0 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
16fb0 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 _step()] recursi
16fc0 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 vely does.** not
16fd0 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 create a new tr
16fe0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a igger context..*
16ff0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 *.** ^This funct
17000 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 ion returns the
17010 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 number of direct
17020 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 row changes in
17030 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 the.** most rece
17040 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 nt INSERT, UPDAT
17050 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 E, or DELETE sta
17060 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 tement within th
17070 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 e same.** trigge
17080 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a r context..**.**
17090 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c ^Thus, when cal
170a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 led from the top
170b0 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e level, this fun
170c0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 ction returns th
170d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
170e0 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f hanges in the mo
170f0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 st recent INSERT
17100 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
17110 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f ETE.** that also
17120 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 occurred at the
17130 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 top level. ^(W
17140 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f ithin the body o
17150 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 f a trigger,.**
17160 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
17170 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 ges() interface
17180 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f can be called to
17190 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
171a0 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 of.** changes i
171b0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
171c0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e tly completed IN
171d0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 SERT, UPDATE, or
171e0 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 DELETE.** state
171f0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
17200 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 body of the same
17210 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 trigger..** How
17220 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 ever, the number
17230 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e returned does n
17240 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 ot include chang
17250 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 es.** caused by
17260 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 subtriggers sinc
17270 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 e those have the
17280 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 ir own context.)
17290 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
172a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
172b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 tal_changes()] i
172c0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
172d0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
172e0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
172f0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
17300 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
17310 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
17320 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e hread makes chan
17330 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 ges on the same
17340 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17350 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 ion.** while [sq
17360 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d lite3_changes()]
17370 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
17380 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
17390 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 ned.** is unpred
173a0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 ictable and not
173b0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 meaningful..*/.i
173c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 nt sqlite3_chang
173d0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
173e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
173f0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 otal Number Of R
17400 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
17410 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
17420 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
17430 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e mber of row chan
17440 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 ges caused by [I
17450 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 NSERT],.** [UPDA
17460 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 TE] or [DELETE]
17470 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 statements since
17480 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
17490 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f onnection] was o
174a0 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 pened..** ^(The
174b0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 count returned b
174c0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f y sqlite3_total_
174d0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 changes() includ
174e0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a es all changes.*
174f0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 * from all [CREA
17500 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 TE TRIGGER | tri
17510 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 gger] contexts a
17520 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 nd changes made
17530 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b by.** [foreign k
17540 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 ey actions]. How
17550 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 ever,.** the cou
17560 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c nt does not incl
17570 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 ude changes used
17580 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 to implement [R
17590 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
175a0 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 nts,.** do rollb
175b0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 acks or ABORT pr
175c0 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 ocessing, or [DR
175d0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 OP TABLE] proces
175e0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f sing. The.** co
175f0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 unt does not inc
17600 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 lude rows of vie
17610 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 ws that fire an
17620 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 [INSTEAD OF trig
17630 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 ger],.** though
17640 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f if the INSTEAD O
17650 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 F trigger makes
17660 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f changes of its o
17670 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 wn, those change
17680 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 s .** are counte
17690 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c d.)^.** ^The sql
176a0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
176b0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f es() function co
176c0 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 unts the changes
176d0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 as soon as.** t
176e0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 he statement tha
176f0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 t makes them is
17700 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 completed (when
17710 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 the statement ha
17720 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 ndle.** is passe
17730 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 d to [sqlite3_re
17740 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 set()] or [sqlit
17750 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e e3_finalize()]).
17760 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
17770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 the [sqlite3_cha
17780 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
17790 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
177a0 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
177b0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c , and the [total
177c0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 _changes() SQL f
177d0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
177e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
177f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
17800 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
17810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17820 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
17830 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
17840 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
17850 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a then the value.
17860 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 ** returned is u
17870 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
17880 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e not meaningful.
17890 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
178a0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 total_changes(sq
178b0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
178c0 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 CAPI3REF: Interr
178d0 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 upt A Long-Runni
178e0 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e ng Query.**.** ^
178f0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 This function ca
17900 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 uses any pending
17910 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
17920 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 ion to abort and
17930 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 .** return at it
17940 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 s earliest oppor
17950 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 tunity. This rou
17960 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c tine is typicall
17970 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 y.** called in r
17980 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 esponse to a use
17990 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 r action such as
179a0 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 pressing "Cance
179b0 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 l".** or Ctrl-C
179c0 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 where the user w
179d0 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 ants a long quer
179e0 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 y operation to h
179f0 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 alt.** immediate
17a00 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ly..**.** ^It is
17a10 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 safe to call th
17a20 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 is routine from
17a30 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 a thread differe
17a40 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 nt from the.** t
17a50 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 hread that is cu
17a60 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 rrently running
17a70 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 the database ope
17a80 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a ration. But it.
17a90 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 ** is not safe t
17aa0 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 o call this rout
17ab0 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 ine with a [data
17ac0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
17ad0 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 that.** is clos
17ae0 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 ed or might clos
17af0 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 e before sqlite3
17b00 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 _interrupt() ret
17b10 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 urns..**.** ^If
17b20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e an SQL operation
17b30 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 is very nearly
17b40 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 finished at the
17b50 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c time when.** sql
17b60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
17b70 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e is called, then
17b80 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 it might not ha
17b90 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 ve an opportunit
17ba0 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 y.** to be inter
17bb0 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 rupted and might
17bc0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d continue to com
17bd0 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e pletion..**.** ^
17be0 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e An SQL operation
17bf0 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 that is interru
17c00 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e pted will return
17c10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 [SQLITE_INTERRU
17c20 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 PT]..** ^If the
17c30 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 interrupted SQL
17c40 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 operation is an
17c50 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
17c60 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 or DELETE.** tha
17c70 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 t is inside an e
17c80 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
17c90 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e ion, then the en
17ca0 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e tire transaction
17cb0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c .** will be roll
17cc0 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 ed back automati
17cd0 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 cally..**.** ^Th
17ce0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
17cf0 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 upt(D) call is i
17d00 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 n effect until a
17d10 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e ll currently run
17d20 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
17d30 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 ements on [datab
17d40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
17d50 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e D complete. ^An
17d60 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d y new SQL statem
17d70 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 ents.** that are
17d80 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 started after t
17d90 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 he sqlite3_inter
17da0 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 rupt() call and
17db0 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 before the .** r
17dc0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 unning statement
17dd0 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 s reaches zero a
17de0 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 re interrupted a
17df0 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 s if they had be
17e00 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 en.** running pr
17e10 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ior to the sqlit
17e20 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 e3_interrupt() c
17e30 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 all. ^New SQL s
17e40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
17e50 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
17e60 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 ter the running
17e70 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 statement count
17e80 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 reaches zero are
17e90 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 .** not effected
17ea0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
17eb0 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 interrupt()..**
17ec0 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ^A call to sqlit
17ed0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 e3_interrupt(D)
17ee0 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e that occurs when
17ef0 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 there are no ru
17f00 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 nning.** SQL sta
17f10 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d tements is a no-
17f20 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 op and has no ef
17f30 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 fect on SQL stat
17f40 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
17f50 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
17f60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
17f70 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 errupt() call re
17f80 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 turns..**.** If
17f90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
17fa0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 nection closes w
17fb0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e hile [sqlite3_in
17fc0 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 terrupt()].** is
17fd0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 running then ba
17fe0 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 d things will li
17ff0 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a kely happen..*/.
18000 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
18010 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
18020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
18030 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
18040 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
18050 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
18060 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
18070 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
18080 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
18090 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
180a0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
180b0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
180c0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
180d0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
180e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
180f0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
18100 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
18110 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
18120 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
18130 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
18140 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
18150 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
18160 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
18170 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
18180 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
18190 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
181a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
181b0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
181c0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
181d0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
181e0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
181f0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
18200 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
18210 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
18220 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
18230 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
18240 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
18250 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
18260 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
18270 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
18280 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
18290 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
182a0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
182b0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
182c0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
182d0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
182e0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
182f0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
18300 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
18310 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
18320 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
18330 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
18340 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
18350 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
18360 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
18370 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
18380 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
18390 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
183a0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
183b0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
183c0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
183d0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
183e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
183f0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
18400 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
18410 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
18420 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
18430 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
18440 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
18450 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
18460 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
18470 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
18480 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
18490 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
184a0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
184b0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
184c0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
184d0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
184e0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
184f0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
18500 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
18510 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
18520 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
18530 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
18540 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
18550 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
18560 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
18570 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
18580 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
18590 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
185a0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
185b0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
185c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
185d0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
185e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
185f0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
18600 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
18610 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
18620 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
18630 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
18640 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
18650 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
18660 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e yte order..*/.in
18670 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 t sqlite3_comple
18680 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 te(const char *s
18690 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ql);.int sqlite3
186a0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
186b0 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
186c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
186d0 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
186e0 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
186f0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
18700 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
18710 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
18720 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 ack function tha
18730 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b t might be invok
18740 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 ed whenever.** a
18750 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 n attempt is mad
18760 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 e to open a data
18770 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 base table that
18780 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
18790 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
187a0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e locked..**.** ^
187b0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
187c0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
187d0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
187e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 or [SQLITE_IOER
187f0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 R_BLOCKED].** is
18800 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
18810 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
18820 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
18830 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
18840 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
18850 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
18860 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
18870 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
18880 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
18890 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
188a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
188b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
188c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
188d0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
188e0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
188f0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
18900 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
18910 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
18920 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
18930 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
18940 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
18950 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
18960 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
18970 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
18980 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f been invoked fo
18990 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 r this locking e
189a0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
189b0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 * busy callback
189c0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 returns 0, then
189d0 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 no additional at
189e0 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 tempts are made
189f0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 to.** access the
18a00 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 database and [S
18a10 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b QLITE_BUSY] or [
18a20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
18a30 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 CKED] is returne
18a40 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 d..** ^If the ca
18a50 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e llback returns n
18a60 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e on-zero, then an
18a70 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a other attempt.**
18a80 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e is made to open
18a90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f the database fo
18aa0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 r reading and th
18ab0 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e e cycle repeats.
18ac0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 .**.** The prese
18ad0 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 nce of a busy ha
18ae0 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 ndler does not g
18af0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 uarantee that it
18b00 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 will be invoked
18b10 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 .** when there i
18b20 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f s lock contentio
18b30 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 n. ^If SQLite de
18b40 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e termines that in
18b50 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a voking the busy.
18b60 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 ** handler could
18b70 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 result in a dea
18b80 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 dlock, it will g
18b90 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 o ahead and retu
18ba0 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
18bb0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 .** or [SQLITE_I
18bc0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e OERR_BLOCKED] in
18bd0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
18be0 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c g the busy handl
18bf0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
18c00 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
18c10 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
18c20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
18c30 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
18c40 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
18c50 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
18c60 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
18c70 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
18c80 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
18c90 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
18ca0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
18cb0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
18cc0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
18cd0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
18ce0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
18cf0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
18d00 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
18d10 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
18d20 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
18d30 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
18d40 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
18d50 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
18d60 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
18d70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
18d80 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
18d90 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
18da0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
18db0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
18dc0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
18dd0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
18de0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
18df0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
18e00 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
18e10 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
18e20 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
18e30 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
18e40 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
18e50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
18e60 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
18e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
18e80 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
18e90 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
18ea0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 ^The [SQLITE_BUS
18eb0 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 Y] error is conv
18ec0 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 erted to [SQLITE
18ed0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a _IOERR_BLOCKED].
18ee0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 ** when SQLite i
18ef0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 s in the middle
18f00 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 of a large trans
18f10 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c action where all
18f20 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 the.** changes
18f30 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 will not fit int
18f40 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 o the in-memory
18f50 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 cache. SQLite w
18f60 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 ill.** already h
18f70 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c old a RESERVED l
18f80 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 ock on the datab
18f90 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 ase file, but it
18fa0 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f needs.** to pro
18fb0 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 mote this lock t
18fc0 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 o EXCLUSIVE so t
18fd0 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c hat it can spill
18fe0 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 cache.** pages
18ff0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 into the databas
19000 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 e file without h
19010 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e arm to concurren
19020 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e t.** readers. ^
19030 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 If it is unable
19040 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c to promote the l
19050 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e ock, then the in
19060 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 -memory.** cache
19070 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e will be left in
19080 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 an inconsistent
19090 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 state and so th
190a0 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 e error.** code
190b0 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d is promoted from
190c0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 the relatively
190d0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 benign [SQLITE_B
190e0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d USY] to.** the m
190f0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 ore severe [SQLI
19100 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
19110 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 ]. ^This error
19120 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a code promotion.*
19130 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f * forces an auto
19140 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f matic rollback o
19150 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 f the changes.
19160 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 See the.** <a hr
19170 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b ef="/cvstrac/wik
19180 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f i?p=CorruptionFo
19190 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 llowingBusyError
191a0 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e ">.** Corruption
191b0 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 FollowingBusyErr
191c0 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 or</a> wiki page
191d0 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f for a discussio
191e0 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 n of why.** this
191f0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a is important..*
19200 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
19210 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
19220 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 e busy handler d
19230 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a efined for each.
19240 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
19250 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 nection]. Setti
19260 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 ng a new busy ha
19270 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 ndler clears any
19280 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
19290 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e et handler.)^ ^
192a0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e Note that callin
192b0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f g [sqlite3_busy_
192c0 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 timeout()].** wi
192d0 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 ll also set or c
192e0 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 lear the busy ha
192f0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
19300 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
19310 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
19320 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
19330 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
19340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19350 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
19360 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
19370 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 . Any such acti
19380 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e ons.** result in
19390 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 undefined behav
193a0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 ior..** .** A bu
193b0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 sy handler must
193c0 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 not close the da
193d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
193e0 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 n.** or [prepare
193f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
19400 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
19410 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 sy handler..*/.i
19420 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
19430 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a handler(sqlite3*
19440 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 , int(*)(void*,i
19450 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a nt), void*);../*
19460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 .** CAPI3REF: Se
19470 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 t A Busy Timeout
19480 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
19490 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c tine sets a [sql
194a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 ite3_busy_handle
194b0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 r | busy handler
194c0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a ] that sleeps.**
194d0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 for a specified
194e0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 amount of time
194f0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 when a table is
19500 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 locked. ^The ha
19510 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c ndler.** will sl
19520 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d eep multiple tim
19530 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 es until at leas
19540 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f t "ms" milliseco
19550 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a nds of sleeping.
19560 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 ** have accumula
19570 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 ted. ^After at
19580 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
19590 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
195a0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 ing,.** the hand
195b0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 ler returns 0 wh
195c0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 ich causes [sqli
195d0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 te3_step()] to r
195e0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 eturn.** [SQLITE
195f0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
19600 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
19610 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
19620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
19630 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c th an argument l
19640 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
19650 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 l to zero.** tur
19660 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 ns off all busy
19670 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 handlers..**.**
19680 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
19690 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
196a0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 y handler for a
196b0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
196c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
196d0 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 on] any any give
196e0 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e n moment. If an
196f0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c other busy handl
19700 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 er.** was define
19710 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 d (using [sqlit
19720 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
19730 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c )]) prior to cal
19740 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 ling.** this rou
19750 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 tine, that other
19760 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
19770 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 cleared.)^.*/.i
19780 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
19790 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
197a0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
197b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
197c0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
197d0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
197e0 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ries.**.** This
197f0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 is a legacy inte
19800 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 rface that is pr
19810 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b eserved for back
19820 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
19830 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 ity..** Use of t
19840 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
19850 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
19860 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 ..**.** Definiti
19870 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
19880 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
19890 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
198a0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
198b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
198c0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
198d0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
198e0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
198f0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
19900 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
19910 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
19920 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
19930 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
19940 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
19950 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
19960 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
19970 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
19980 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
19990 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
199a0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
199b0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
199c0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
199d0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
199e0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
199f0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
19a00 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
19a10 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
19a20 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
19a30 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
19a40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
19a50 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
19a60 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
19a70 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
19a80 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
19a90 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
19aa0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
19ab0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
19ac0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
19ad0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
19ae0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
19af0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
19b00 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
19b10 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
19b20 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
19b30 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
19b40 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
19b50 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
19b60 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
19b70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
19b80 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
19b90 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
19ba0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
19bb0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
19bc0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
19bd0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
19be0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
19bf0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
19c00 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
19c10 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
19c20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
19c30 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
19c40 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
19c50 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
19c60 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
19c70 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
19c80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
19c90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e ]..**.** ^(As an
19ca0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
19cb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
19cc0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
19cd0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
19ce0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
19cf0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
19d00 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
19d10 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
19d20 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
19d30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
19d40 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
19d50 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
19d60 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
19d70 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
19d80 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
19d90 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
19da0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
19db0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
19dc0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
19dd0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
19de0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
19df0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
19e00 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
19e10 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
19e20 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
19e30 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
19e40 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
19e50 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
19e60 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
19e70 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
19e80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
19e90 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
19ea0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
19eb0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
19ec0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
19ed0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
19ee0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
19ef0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
19f00 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
19f10 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
19f20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
19f30 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
19f40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
19f50 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
19f60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
19f70 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
19f80 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
19f90 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
19fa0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
19fb0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
19fc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
19fd0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
19fe0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
19ff0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
1a000 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
1a010 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
1a020 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
1a030 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
1a040 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
1a050 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
1a060 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 nd returns a res
1a070 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 ult table to the
1a080 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 .** pointer give
1a090 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 n in its 3rd par
1a0a0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 ameter..**.** Af
1a0b0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 ter the applicat
1a0c0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
1a0d0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 with the result
1a0e0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 from sqlite3_ge
1a0f0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 t_table(),.** it
1a100 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 must pass the r
1a110 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
1a120 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
1a130 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
1a140 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
1a150 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
1a160 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
1a170 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
1a180 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
1a190 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
1a1a0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
1a1b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1a1c0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
1a1d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
1a1e0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
1a1f0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1a200 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
1a210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
1a220 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
1a230 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
1a240 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
1a250 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
1a260 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1a270 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
1a280 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
1a290 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
1a2a0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
1a2b0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
1a2c0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1a2d0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
1a2e0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
1a2f0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
1a300 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
1a310 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
1a320 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
1a330 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
1a340 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
1a350 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
1a360 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
1a370 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
1a380 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
1a390 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
1a3a0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
1a3b0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
1a3c0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
1a3d0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
1a3e0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
1a3f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
1a400 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
1a410 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e errmsg()]..*/.in
1a420 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 t sqlite3_get_ta
1a430 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a ble(. sqlite3 *
1a440 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 db, /*
1a450 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
1a460 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
1a470 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 *zSql, /* S
1a480 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 QL to be evaluat
1a490 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a ed */. char ***
1a4a0 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a pazResult, /*
1a4b0 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 Results of the
1a4c0 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a query */. int *
1a4d0 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 pnRow,
1a4e0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 /* Number of re
1a4f0 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 sult rows writte
1a500 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 n here */. int
1a510 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 *pnColumn,
1a520 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 /* Number of r
1a530 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 esult columns wr
1a540 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
1a550 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 char **pzErrmsg
1a560 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
1a570 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
1a580 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 */.);.void sqlit
1a590 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
1a5a0 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
1a5b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
1a5c0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
1a5d0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
1a5e0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
1a5f0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b outines are work
1a600 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 -alikes of the "
1a610 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
1a620 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
1a630 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
1a640 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
1a650 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1a660 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
1a670 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1a680 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
1a690 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
1a6a0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
1a6b0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
1a6c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
1a6d0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
1a6e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1a6f0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
1a700 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
1a710 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
1a720 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
1a730 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1a740 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1a750 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
1a760 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
1a770 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
1a780 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
1a790 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
1a7a0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
1a7b0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
1a7c0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
1a7d0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
1a7e0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
1a7f0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
1a800 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
1a810 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
1a820 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
1a830 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
1a840 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1a850 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
1a860 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
1a870 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
1a880 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 rameter. Note th
1a890 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 at the order of
1a8a0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f the.** first two
1a8b0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 parameters is r
1a8c0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 eversed from snp
1a8d0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 rintf().)^ This
1a8e0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
1a8f0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
1a900 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
1a910 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
1a920 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
1a930 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
1a940 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 ^(Note also tha
1a950 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e t sqlite3_snprin
1a960 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tf().** returns
1a970 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 a pointer to its
1a980 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 buffer instead
1a990 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
1a9a0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 .** characters a
1a9b0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 ctually written
1a9c0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e into the buffer.
1a9d0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 )^ We admit tha
1a9e0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
1a9f0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
1aa00 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
1aa10 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
1aa20 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
1aa30 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
1aa40 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
1aa50 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
1aa60 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
1aa70 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
1aa80 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
1aa90 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 ..**.** ^As long
1aaa0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 as the buffer s
1aab0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 ize is greater t
1aac0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 han zero, sqlite
1aad0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1aae0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
1aaf0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c the buffer is al
1ab00 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
1ab10 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 ated. ^The firs
1ab20 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
1ab30 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
1ab40 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
1ab50 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
1ab60 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
1ab70 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
1ab80 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
1ab90 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
1aba0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
1abb0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
1abc0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
1abd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1abe0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 te3_vsnprintf()
1abf0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 routine is a var
1ac00 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 args version of
1ac10 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1ac20 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ()..**.** These
1ac30 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
1ac40 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
1ac50 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
1ac60 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
1ac70 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
1ac80 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
1ac90 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
1aca0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
1acb0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
1acc0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
1acd0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
1ace0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
1acf0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 re "%q", "%Q", a
1ad00 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e nd "%z" options.
1ad10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 .**.** ^(The %q
1ad20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
1ad30 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
1ad40 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
1ad50 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
1ad60 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
1ad70 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
1ad80 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
1ad90 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
1ada0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
1adb0 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
1adc0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
1add0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 ing literal.)^
1ade0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 By doubling each
1adf0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 '\''.** charact
1ae00 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 er it escapes th
1ae10 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 at character and
1ae20 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 allows it to be
1ae30 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a inserted into.*
1ae40 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a * the string..**
1ae50 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c .** For example,
1ae60 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 assume the stri
1ae70 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 ng variable zTex
1ae80 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 t contains text
1ae90 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1aea0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1aeb0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 re>.** char *zT
1aec0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 ext = "It's a ha
1aed0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f ppy day!";.** </
1aee0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1aef0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 >.**.** One can
1af00 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e use this text in
1af10 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
1af20 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
1af30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1af40 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1af50 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
1af60 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
1af70 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
1af80 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
1af90 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
1afa0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
1afb0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
1afc0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
1afd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1afe0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 ote>.**.** Becau
1aff0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 se the %q format
1b000 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c string is used,
1b010 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 the '\'' charac
1b020 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 ter in zText.**
1b030 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 is escaped and t
1b040 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 he SQL generated
1b050 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
1b060 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1b070 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
1b080 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
1b090 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 ALUES('It''s a h
1b0a0 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c appy day!').** <
1b0b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1b0c0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 e>.**.** This is
1b0d0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 correct. Had w
1b0e0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 e used %s instea
1b0f0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e d of %q, the gen
1b100 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f erated SQL.** wo
1b110 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 uld have looked
1b120 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
1b130 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1b140 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
1b150 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
1b160 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 ('It's a happy d
1b170 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ay!');.** </pre>
1b180 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1b190 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 .** This second
1b1a0 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 example is an SQ
1b1b0 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 L syntax error.
1b1c0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 As a general ru
1b1d0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a le you should.**
1b1e0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 always use %q i
1b1f0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 nstead of %s whe
1b200 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 n inserting text
1b210 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c into a string l
1b220 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 iteral..**.** ^(
1b230 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f The %Q option wo
1b240 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 rks like %q exce
1b250 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 pt it also adds
1b260 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 single quotes ar
1b270 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 ound.** the outs
1b280 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c ide of the total
1b290 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 string. Additi
1b2a0 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 onally, if the p
1b2b0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a arameter in the.
1b2c0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 ** argument list
1b2d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1b2e0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 er, %Q substitut
1b2f0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c es the text "NUL
1b300 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 L" (without.** s
1b310 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e ingle quotes).)^
1b320 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c So, for exampl
1b330 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 e, one could say
1b340 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1b350 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
1b360 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
1b370 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
1b380 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
1b390 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 LUES(%Q)", zText
1b3a0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
1b3b0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
1b3c0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
1b3d0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
1b3e0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1b3f0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1b400 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c code above will
1b410 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 render a correc
1b420 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
1b430 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 in the zSQL.** v
1b440 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 ariable even if
1b450 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 the zText variab
1b460 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 le is a NULL poi
1b470 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 nter..**.** ^(Th
1b480 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
1b490 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c g option works l
1b4a0 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 ike "%s" but wit
1b4b0 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
1b4c0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
1b4d0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
1b4e0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
1b4f0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
1b500 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
1b510 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
1b520 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
1b530 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a ing.)^.*/.char *
1b540 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1b550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 const char*,...)
1b560 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f ;.char *sqlite3_
1b570 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 vmprintf(const c
1b580 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
1b590 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e char *sqlite3_sn
1b5a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a printf(int,char*
1b5b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e ,const char*, ..
1b5c0 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 .);.char *sqlite
1b5d0 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 3_vsnprintf(int,
1b5e0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1b5f0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a *, va_list);../*
1b600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
1b610 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
1b620 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 Subsystem.**.**
1b630 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
1b640 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 uses these three
1b650 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c routines for al
1b660 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 l of its own.**
1b670 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 internal memory
1b680 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
1b690 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 . "Core" in the
1b6a0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
1b6b0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e e.** does not in
1b6c0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d clude operating-
1b6d0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 system specific
1b6e0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
1b6f0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 on. The.** Wind
1b700 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 ows VFS uses nat
1b710 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 ive malloc() and
1b720 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 free() for some
1b730 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
1b740 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1b750 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 malloc() routine
1b760 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1b770 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a er to a block.**
1b780 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 of memory at le
1b790 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c ast N bytes in l
1b7a0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 ength, where N i
1b7b0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e s the parameter.
1b7c0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
1b7d0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
1b7e0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
1b7f0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
1b800 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
1b810 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
1b820 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 r. ^If the para
1b830 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 meter N to.** sq
1b840 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
1b850 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 s zero or negati
1b860 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ve then sqlite3_
1b870 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 malloc() returns
1b880 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
1b890 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 er..**.** ^Calli
1b8a0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 ng sqlite3_free(
1b8b0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
1b8c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 previously retu
1b8d0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
1b8e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
1b8f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1b900 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d releases that m
1b910 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 emory so.** that
1b920 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 it might be reu
1b930 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 sed. ^The sqlit
1b940 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e e3_free() routin
1b950 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 e is.** a no-op
1b960 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 if is called wit
1b970 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
1b980 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c . Passing a NUL
1b990 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 L pointer.** to
1b9a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
1b9b0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 s harmless. Aft
1b9c0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 er being freed,
1b9d0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 memory.** should
1b9e0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 neither be read
1b9f0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 nor written. E
1ba00 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 ven reading prev
1ba10 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 iously freed.**
1ba20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 memory might res
1ba30 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 ult in a segment
1ba40 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f ation fault or o
1ba50 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f ther severe erro
1ba60 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 r..** Memory cor
1ba70 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 ruption, a segme
1ba80 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f ntation fault, o
1ba90 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 r other severe e
1baa0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 rror.** might re
1bab0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f sult if sqlite3_
1bac0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 free() is called
1bad0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c with a non-NULL
1bae0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a pointer that.**
1baf0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 was not obtaine
1bb00 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d d from sqlite3_m
1bb10 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1bb20 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a e3_realloc()..**
1bb30 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
1bb40 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 3_realloc() inte
1bb50 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
1bb60 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 o resize a.** pr
1bb70 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ior memory alloc
1bb80 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c ation to be at l
1bb90 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 east N bytes, wh
1bba0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 ere N is the.**
1bbb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1bbc0 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c . The memory al
1bbd0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 location to be r
1bbe0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 esized is the fi
1bbf0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
1bc00 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 .)^ ^ If the fir
1bc10 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
1bc20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1bc30 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 ).** is a NULL p
1bc40 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 ointer then its
1bc50 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e behavior is iden
1bc60 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 tical to calling
1bc70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
1bc80 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 oc(N) where N is
1bc90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1bca0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1bcb0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e _realloc()..** ^
1bcc0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 If the second pa
1bcd0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
1bce0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 e3_realloc() is
1bcf0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 zero or.** negat
1bd00 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 ive then the beh
1bd10 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 avior is exactly
1bd20 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c the same as cal
1bd30 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
1bd40 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 free(P) where P
1bd50 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
1bd60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1bd70 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 3_realloc()..**
1bd80 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 ^sqlite3_realloc
1bd90 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 () returns a poi
1bda0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
1bdb0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f allocation.** o
1bdc0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 f at least N byt
1bdd0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 es in size or NU
1bde0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 LL if sufficient
1bdf0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 memory is unava
1be00 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d ilable..** ^If M
1be10 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 is the size of
1be20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1be30 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e tion, then min(N
1be40 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 ,M) bytes.** of
1be50 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1be60 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 tion are copied
1be70 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 into the beginni
1be80 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 ng of buffer ret
1be90 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 urned.** by sqli
1bea0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e te3_realloc() an
1beb0 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f d the prior allo
1bec0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e cation is freed.
1bed0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
1bee0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e realloc() return
1bef0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 s NULL, then the
1bf00 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
1bf10 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 n.** is not free
1bf20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 d..**.** ^The me
1bf30 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 mory returned by
1bf40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1bf50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 ) and sqlite3_re
1bf60 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c alloc().** is al
1bf70 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 ways aligned to
1bf80 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 at least an 8 by
1bf90 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 te boundary, or
1bfa0 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 to a.** 4 byte b
1bfb0 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b oundary if the [
1bfc0 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c SQLITE_4_BYTE_AL
1bfd0 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f IGNED_MALLOC] co
1bfe0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 mpile-time.** op
1bff0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a tion is used..**
1c000 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 .** In SQLite ve
1c010 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 rsion 3.5.0 and
1c020 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 3.5.1, it was po
1c030 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 ssible to define
1c040 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f .** the SQLITE_O
1c050 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 MIT_MEMORY_ALLOC
1c060 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c ATION which woul
1c070 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c d cause the buil
1c080 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e t-in.** implemen
1c090 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 tation of these
1c0a0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f routines to be o
1c0b0 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 mitted. That ca
1c0c0 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e pability.** is n
1c0d0 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 o longer provide
1c0e0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 d. Only built-i
1c0f0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
1c100 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e ors can be used.
1c110 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 .**.** Prior to
1c120 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
1c130 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f .7.10, the Windo
1c140 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 ws OS interface
1c150 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 layer called.**
1c160 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f the system mallo
1c170 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 c() and free() d
1c180 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e irectly when con
1c190 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e verting.** filen
1c1a0 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 ames between the
1c1b0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 UTF-8 encoding
1c1c0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a used by SQLite.*
1c1d0 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 * and whatever f
1c1e0 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 ilename encoding
1c1f0 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
1c200 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f particular Windo
1c210 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 ws.** installati
1c220 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f on. Memory allo
1c230 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 cation errors we
1c240 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 re detected, but
1c250 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 .** they were re
1c260 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b ported back as [
1c270 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d SQLITE_CANTOPEN]
1c280 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 or.** [SQLITE_I
1c290 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 OERR] rather tha
1c2a0 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d n [SQLITE_NOMEM]
1c2b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e ..**.** The poin
1c2c0 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ter arguments to
1c2d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
1c2e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 ] and [sqlite3_r
1c2f0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 ealloc()].** mus
1c300 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c t be either NULL
1c310 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 or else pointer
1c320 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 s obtained from
1c330 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 a prior.** invoc
1c340 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 ation of [sqlite
1c350 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 3_malloc()] or [
1c360 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1c370 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 )] that have.**
1c380 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c not yet been rel
1c390 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eased..**.** The
1c3a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
1c3b0 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 t not read or wr
1c3c0 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a ite any part of.
1c3d0 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 ** a block of me
1c3e0 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 mory after it ha
1c3f0 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 s been released
1c400 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
1c410 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 3_free()] or [sq
1c420 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1c430 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
1c440 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a e3_malloc(int);.
1c450 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
1c460 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 alloc(void*, int
1c470 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
1c480 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a free(void*);../*
1c490 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
1c4a0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
1c4b0 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
1c4c0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
1c4d0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
1c4e0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
1c4f0 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
1c500 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
1c510 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
1c520 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
1c530 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
1c540 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
1c550 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
1c560 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
1c570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1c580 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
1c590 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
1c5a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
1c5b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
1c5c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
1c5d0 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
1c5e0 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
1c5f0 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
1c600 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
1c610 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
1c620 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1c630 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
1c640 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
1c650 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
1c660 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1c670 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
1c680 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
1c690 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
1c6a0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
1c6b0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
1c6c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1c6d0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
1c6e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1c6f0 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
1c700 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
1c710 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
1c720 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
1c730 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1c740 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
1c750 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
1c760 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
1c770 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
1c780 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
1c790 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
1c7a0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
1c7b0 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
1c7c0 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
1c7d0 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
1c7e0 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
1c7f0 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
1c800 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1c810 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
1c820 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
1c830 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
1c840 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1c850 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
1c860 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
1c870 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
1c880 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1c890 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
1c8a0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
1c8b0 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
1c8c0 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 eset..*/.sqlite3
1c8d0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d _int64 sqlite3_m
1c8e0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 emory_used(void)
1c8f0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 ;.sqlite3_int64
1c900 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1c910 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 ighwater(int res
1c920 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 etFlag);../*.**
1c930 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f CAPI3REF: Pseudo
1c940 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 -Random Number G
1c950 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 enerator.**.** S
1c960 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 QLite contains a
1c970 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 high-quality ps
1c980 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 eudo-random numb
1c990 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 er generator (PR
1c9a0 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 NG) used to.** s
1c9b0 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f elect random [RO
1c9c0 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 WID | ROWIDs] wh
1c9d0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 en inserting new
1c9e0 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 records into a
1c9f0 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c table that.** al
1ca00 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c ready uses the l
1ca10 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 argest possible
1ca20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 [ROWID]. The PR
1ca30 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 NG is also used
1ca40 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 for.** the build
1ca50 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 -in random() and
1ca60 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 randomblob() SQ
1ca70 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 L functions. Th
1ca80 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
1ca90 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 ows.** applicati
1caa0 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 ons to access th
1cab0 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 e same PRNG for
1cac0 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a other purposes..
1cad0 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f **.** ^A call to
1cae0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 this routine st
1caf0 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 ores N bytes of
1cb00 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
1cb10 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 buffer P..**.**
1cb20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 ^The first time
1cb30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
1cb40 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 invoked (either
1cb50 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 internally or by
1cb60 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
1cb70 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 ion) the PRNG is
1cb80 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 seeded using ra
1cb90 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 ndomness obtaine
1cba0 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 d.** from the xR
1cbb0 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 andomness method
1cbc0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 of the default
1cbd0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
1cbe0 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c ject..** ^On all
1cbf0 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f subsequent invo
1cc00 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 cations, the pse
1cc10 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
1cc20 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
1cc30 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
1cc40 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
1cc50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1cc60 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
1cc70 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f ** method..*/.vo
1cc80 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f id sqlite3_rando
1cc90 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
1cca0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
1ccb0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
1ccc0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
1ccd0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a on Callbacks.**.
1cce0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
1ccf0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 registers an au
1cd00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1cd10 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 k with a particu
1cd20 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
1cd30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 connection], su
1cd40 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 pplied in the fi
1cd50 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
1cd60 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
1cd70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1cd80 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
1cd90 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
1cda0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
1cdb0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1cdc0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
1cdd0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
1cde0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
1cdf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1ce00 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
1ce10 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1ce20 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a ]. ^At various.
1ce30 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
1ce40 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
1ce50 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
1ce60 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
1ce70 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
1ce80 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
1ce90 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
1cea0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
1ceb0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
1cec0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
1ced0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e are allowed. ^
1cee0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
1cef0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
1cf00 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
1cf10 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
1cf20 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
1cf30 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
1cf40 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
1cf50 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
1cf60 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
1cf70 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
1cf80 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
1cf90 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
1cfa0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
1cfb0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
1cfc0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
1cfd0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
1cfe0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 h an error. ^If
1cff0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1d000 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1d010 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 .** any value ot
1d020 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
1d030 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
1d040 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
1d050 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 E_DENY].** then
1d060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
1d070 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
1d080 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
1d090 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 at triggered.**
1d0a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 the authorizer w
1d0b0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
1d0c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
1d0d0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
1d0e0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1d0f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 [SQLITE_OK], tha
1d100 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 t means the oper
1d110 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 ation.** request
1d120 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e ed is ok. ^When
1d130 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1d140 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 turns [SQLITE_DE
1d150 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c NY], the.** [sql
1d160 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1d170 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
1d180 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
1d190 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 ered the.** auth
1d1a0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
1d1b0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
1d1c0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e essage explainin
1d1d0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 g that.** access
1d1e0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a is denied. .**.
1d1f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
1d200 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
1d210 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1d220 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
1d230 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
1d240 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
1d250 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1d260 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 izer() interface
1d270 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
1d280 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
1d290 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
1d2a0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
1d2b0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
1d2c0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
1d2d0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
1d2e0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
1d2f0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e be authorized. ^
1d300 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
1d310 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
1d320 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
1d330 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
1d340 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
1d350 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
1d360 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
1d370 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
1d380 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
1d390 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 orized..**.** ^I
1d3a0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
1d3b0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
1d3c0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
1d3d0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
1d3e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
1d3f0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
1d400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1d410 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
1d420 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
1d430 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
1d440 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
1d450 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
1d460 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
1d470 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
1d480 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
1d490 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
1d4a0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
1d4b0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
1d4c0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
1d4d0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
1d4e0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
1d4f0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
1d500 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
1d510 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 le..** ^If the a
1d520 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
1d530 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
1d540 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
1d550 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
1d560 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
1d570 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
1d580 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
1d590 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
1d5a0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
1d5b0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
1d5c0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
1d5d0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
1d5e0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
1d5f0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
1d600 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
1d610 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
1d620 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
1d630 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
1d640 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
1d650 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
1d660 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1d670 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
1d680 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
1d690 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
1d6a0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
1d6b0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
1d6c0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
1d6d0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
1d6e0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
1d6f0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
1d700 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
1d710 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
1d720 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
1d730 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
1d740 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
1d750 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
1d760 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
1d770 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
1d780 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
1d790 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
1d7a0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
1d7b0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
1d7c0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
1d7d0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
1d7e0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
1d7f0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
1d800 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
1d810 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
1d820 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
1d830 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
1d840 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
1d850 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
1d860 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
1d870 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
1d880 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
1d890 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
1d8a0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
1d8b0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
1d8c0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
1d8d0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
1d8e0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
1d8f0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
1d900 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
1d910 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
1d920 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
1d930 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
1d940 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
1d950 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
1d960 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
1d970 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c zer..**.** ^(Onl
1d980 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
1d990 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
1d9a0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
1d9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1d9c0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
1d9d0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
1d9e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1d9f0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
1da00 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
1da10 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 .)^ ^Disable th
1da20 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
1da30 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
1da40 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
1da50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
1da60 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
1da70 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
1da80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1da90 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
1daa0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
1dab0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
1dac0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1dad0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1dae0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
1daf0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
1db00 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
1db10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
1db20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
1db30 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
1db40 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
1db50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
1db60 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
1db70 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
1db80 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
1db90 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 ** ^When [sqlite
1dba0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1dbb0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 is used to prepa
1dbc0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 re a statement,
1dbd0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
1dbe0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 might be re-pre
1dbf0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 pared during [sq
1dc00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 lite3_step()] du
1dc10 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d e to a .** schem
1dc20 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 a change. Hence
1dc30 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
1dc40 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 n should ensure
1dc50 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 that the.** corr
1dc60 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 ect authorizer c
1dc70 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 allback remains
1dc80 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 in place during
1dc90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
1dca0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 p()]..**.** ^Not
1dcb0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
1dcc0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1dcd0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
1dce0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
1dcf0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
1dd00 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
1dd10 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
1dd20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
1dd30 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
1dd40 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
1dd50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1dd60 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 , unless.** as s
1dd70 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 tated in the pre
1dd80 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c vious paragraph,
1dd90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
1dda0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 invokes.** sqlit
1ddb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
1ddc0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 to reprepare a s
1ddd0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 tatement after a
1dde0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a schema change..
1ddf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 */.int sqlite3_s
1de00 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
1de10 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
1de20 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
1de30 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
1de40 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1de50 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1de60 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
1de70 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
1de80 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
1de90 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
1dea0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
1deb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1dec0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1ded0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1dee0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
1def0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
1df00 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
1df10 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
1df20 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
1df30 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
1df40 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
1df50 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
1df60 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
1df70 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1df80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1df90 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
1dfa0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
1dfb0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
1dfc0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
1dfd0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 Note that SQLITE
1dfe0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 _IGNORE is also
1dff0 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 used as a [SQLIT
1e000 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 E_ROLLBACK | ret
1e010 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f urn code].** fro
1e020 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
1e030 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 tab_on_conflict(
1e040 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f )] interface..*/
1e050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e060 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 DENY 1 /* Ab
1e070 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 ort the SQL stat
1e080 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 ement with an er
1e090 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ror */.#define S
1e0a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 QLITE_IGNORE 2
1e0b0 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 /* Don't allow
1e0c0 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 access, but don'
1e0d0 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 t generate an er
1e0e0 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 ror */../*.** CA
1e0f0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a PI3REF: Authoriz
1e100 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a er Action Codes.
1e110 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 **.** The [sqlit
1e120 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1e130 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 r()] interface r
1e140 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 egisters a callb
1e150 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ack function.**
1e160 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 that is invoked
1e170 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 to authorize cer
1e180 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 tain SQL stateme
1e190 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 nt actions. The
1e1a0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
1e1b0 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c eter to the call
1e1c0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 back is an integ
1e1d0 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 er code that spe
1e1e0 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 cifies.** what a
1e1f0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 ction is being a
1e200 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 uthorized. Thes
1e210 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 e are the intege
1e220 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 r action codes t
1e230 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f hat.** the autho
1e240 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
1e250 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a ay be passed..**
1e260 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e .** These action
1e270 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 code values sig
1e280 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f nify what kind o
1e290 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 f operation is t
1e2a0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a o be.** authoriz
1e2b0 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 ed. The 3rd and
1e2c0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 4th parameters
1e2d0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 to the authoriza
1e2e0 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b tion.** callback
1e2f0 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 function will b
1e300 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 e parameters or
1e310 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f NULL depending o
1e320 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 n which of these
1e330 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 .** codes is use
1e340 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1e350 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 parameter. ^(Th
1e360 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 5th parameter
1e370 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 to the.** author
1e380 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1e390 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
1e3a0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e database ("main
1e3b0 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 ", "temp",.** et
1e3c0 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c c.) if applicabl
1e3d0 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 e.)^ ^The 6th p
1e3e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1e3f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1e400 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ack.** is the na
1e410 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d me of the inner-
1e420 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 most trigger or
1e430 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 view that is res
1e440 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 ponsible for.**
1e450 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d the access attem
1e460 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 pt or NULL if th
1e470 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 is access attemp
1e480 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 t is directly fr
1e490 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 om.** top-level
1e4a0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a SQL code..*/./**
1e4b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e4c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1e4d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a ********* 3rd **
1e4e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a ********** 4th *
1e4f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 **********/.#def
1e500 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1e510 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 E_INDEX
1e520 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 1 /* Index Na
1e530 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1e540 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1e550 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1e560 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
1e570 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 2 /* Table Nam
1e580 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1e590 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1e5a0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1e5b0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 TEMP_INDEX 3
1e5c0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
1e5d0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
1e5e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1e5f0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
1e600 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 EMP_TABLE 4
1e610 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1e620 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1e630 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1e640 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
1e650 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 MP_TRIGGER 5
1e660 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1e670 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1e680 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1e690 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
1e6a0 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 P_VIEW 6
1e6b0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
1e6c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1e6d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1e6e0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 LITE_CREATE_TRIG
1e6f0 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f GER 7 /
1e700 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
1e710 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1e720 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1e730 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 ITE_CREATE_VIEW
1e740 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 8 /*
1e750 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
1e760 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1e770 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1e780 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 TE_DELETE
1e790 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 9 /*
1e7a0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1e7b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1e7c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1e7d0 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 E_DROP_INDEX
1e7e0 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 10 /* I
1e7f0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
1e800 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1e810 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e820 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 _DROP_TABLE
1e830 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 11 /* Ta
1e840 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
1e850 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1e860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1e870 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 DROP_TEMP_INDEX
1e880 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 12 /* Ind
1e890 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1e8a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1e8b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1e8c0 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ROP_TEMP_TABLE
1e8d0 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 13 /* Tabl
1e8e0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1e8f0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1e900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1e910 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 OP_TEMP_TRIGGER
1e920 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 14 /* Trigg
1e930 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
1e940 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1e950 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1e960 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 P_TEMP_VIEW
1e970 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 15 /* View N
1e980 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
1e990 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1e9a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1e9b0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
1e9c0 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 16 /* Trigger
1e9d0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1e9e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1e9f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1ea00 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 VIEW
1ea10 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 17 /* View Nam
1ea20 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1ea30 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1ea40 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 ne SQLITE_INSERT
1ea50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
1ea60 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
1ea70 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1ea80 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ea90 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 e SQLITE_PRAGMA
1eaa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
1eab0 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d /* Pragma Nam
1eac0 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 e 1st arg or
1ead0 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 NULL */.#define
1eae0 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 SQLITE_READ
1eaf0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20
1eb00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1eb10 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 Column Name
1eb20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1eb30 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 SQLITE_SELECT
1eb40 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 21
1eb50 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
1eb60 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1eb70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1eb80 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f QLITE_TRANSACTIO
1eb90 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 N 22
1eba0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
1ebb0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1ebc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1ebd0 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 LITE_UPDATE
1ebe0 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 23 /
1ebf0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1ec00 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 Column Name
1ec10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1ec20 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 ITE_ATTACH
1ec30 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 24 /*
1ec40 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 Filename
1ec50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1ec60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1ec70 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 TE_DETACH
1ec80 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 25 /*
1ec90 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
1eca0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1ecb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ecc0 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 E_ALTER_TABLE
1ecd0 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 26 /* D
1ece0 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 atabase Name T
1ecf0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1ed00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ed10 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 _REINDEX
1ed20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 27 /* In
1ed30 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 dex Name NU
1ed40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1ed50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ed60 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 ANALYZE
1ed70 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 28 /* Tab
1ed80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1ed90 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1eda0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1edb0 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 REATE_VTABLE
1edc0 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 29 /* Tabl
1edd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
1ede0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
1edf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
1ee00 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 OP_VTABLE
1ee10 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 30 /* Table
1ee20 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c Name Modul
1ee30 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 e Name */.#d
1ee40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e efine SQLITE_FUN
1ee50 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 CTION
1ee60 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 31 /* NULL
1ee70 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 Functi
1ee80 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 on Name */.#de
1ee90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 fine SQLITE_SAVE
1eea0 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 POINT
1eeb0 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 32 /* Operati
1eec0 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 on Savepoi
1eed0 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 nt Name */.#def
1eee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 ine SQLITE_COPY
1eef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
1ef00 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 0 /* No longe
1ef10 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a r used */../*.**
1ef20 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 CAPI3REF: Traci
1ef30 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 ng And Profiling
1ef40 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
1ef50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1ef60 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 register callbac
1ef70 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 k functions that
1ef80 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 can be used for
1ef90 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 .** tracing and
1efa0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 profiling the ex
1efb0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 ecution of SQL s
1efc0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
1efd0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
1efe0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
1eff0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 ed by sqlite3_tr
1f000 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ace() is invoked
1f010 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 at.** various t
1f020 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c imes when an SQL
1f030 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 statement is be
1f040 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 ing run by [sqli
1f050 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 te3_step()]..**
1f060 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
1f070 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ce() callback is
1f080 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 invoked with a
1f090 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 UTF-8 rendering
1f0a0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 of the.** SQL st
1f0b0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 atement text as
1f0c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 the statement fi
1f0d0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 rst begins execu
1f0e0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 ting..** ^(Addit
1f0f0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 ional sqlite3_tr
1f100 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 ace() callbacks
1f110 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 might occur.** a
1f120 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 s each triggered
1f130 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 subprogram is e
1f140 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c ntered. The cal
1f150 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 lbacks for trigg
1f160 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 ers.** contain a
1f170 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 UTF-8 SQL comme
1f180 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 nt that identifi
1f190 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 es the trigger.)
1f1a0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ^.**.** The [SQL
1f1b0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c ITE_TRACE_SIZE_L
1f1c0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 IMIT] compile-ti
1f1d0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 me option can be
1f1e0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a used to limit.*
1f1f0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 * the length of
1f200 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 [bound parameter
1f210 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 ] expansion in t
1f220 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c he output of sql
1f230 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a ite3_trace()..**
1f240 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
1f250 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
1f260 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
1f270 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e _profile() is in
1f280 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 voked.** as each
1f290 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 SQL statement f
1f2a0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 inishes. ^The p
1f2b0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 rofile callback
1f2c0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 contains.** the
1f2d0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
1f2e0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 nt text and an e
1f2f0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d stimate of wall-
1f300 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 clock time.** of
1f310 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 how long that s
1f320 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f tatement took to
1f330 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 run. ^The prof
1f340 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ile callback.**
1f350 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 time is in units
1f360 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c of nanoseconds,
1f370 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 however the cur
1f380 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 rent implementat
1f390 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 ion.** is only c
1f3a0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 apable of millis
1f3b0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e econd resolution
1f3c0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 so the six leas
1f3d0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a t significant.**
1f3e0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 digits in the t
1f3f0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c ime are meaningl
1f400 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 ess. Future ver
1f410 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a sions of SQLite.
1f420 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 ** might provide
1f430 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 greater resolut
1f440 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 ion on the profi
1f450 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 ler callback. T
1f460 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 he.** sqlite3_pr
1f470 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e ofile() function
1f480 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 is considered e
1f490 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 xperimental and
1f4a0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f is.** subject to
1f4b0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 change in futur
1f4c0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1f4d0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 Lite..*/.void *s
1f4e0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
1f4f0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
1f500 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
1f510 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
1f520 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 .SQLITE_EXPERIME
1f530 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 NTAL void *sqlit
1f540 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 e3_profile(sqlit
1f550 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 e3*,. void(*xP
1f560 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f rofile)(void*,co
1f570 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 nst char*,sqlite
1f580 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 3_uint64), void*
1f590 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f5a0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 EF: Query Progre
1f5b0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a ss Callbacks.**.
1f5c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
1f5d0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
1f5e0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 (D,N,X,P) interf
1f5f0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 ace causes the c
1f600 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
1f610 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f ion X to be invo
1f620 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 ked periodically
1f630 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e during long run
1f640 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ning calls to.**
1f650 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
1f660 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ], [sqlite3_step
1f670 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
1f680 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f _get_table()] fo
1f690 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f r.** database co
1f6a0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 nnection D. An
1f6b0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 example use for
1f6c0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 this.** interfac
1f6d0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 e is to keep a G
1f6e0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e UI updated durin
1f6f0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e g a large query.
1f700 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 .**.** ^The para
1f710 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 meter P is passe
1f720 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
1f730 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 only parameter
1f740 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 to the .** callb
1f750 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 ack function X.
1f760 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
1f770 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 N is the approxi
1f780 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a mate number of .
1f790 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 ** [virtual mach
1f7a0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 ine instructions
1f7b0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 ] that are evalu
1f7c0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 ated between suc
1f7d0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 cessive.** invoc
1f7e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 ations of the ca
1f7f0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e llback X. ^If N
1f800 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e is less than on
1f810 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 e then the progr
1f820 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 ess.** handler i
1f830 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a s disabled..**.*
1f840 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 * ^Only a single
1f850 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
1f860 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 r may be defined
1f870 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 at one time per
1f880 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1f890 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 nnection]; setti
1f8a0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 ng a new progres
1f8b0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c s handler cancel
1f8c0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 s the.** old one
1f8d0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 . ^Setting para
1f8e0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 meter X to NULL
1f8f0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f disables the pro
1f900 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a gress handler..*
1f910 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 * ^The progress
1f920 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 handler is also
1f930 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 disabled by sett
1f940 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 ing N to a value
1f950 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e less.** than 1.
1f960 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 .**.** ^If the p
1f970 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b rogress callback
1f980 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
1f990 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e o, the operation
1f9a0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 is.** interrupt
1f9b0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 ed. This featur
1f9c0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
1f9d0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 implement a.**
1f9e0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 "Cancel" button
1f9f0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 on a GUI progres
1fa00 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a s dialog box..**
1fa10 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 .** The progress
1fa20 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 handler callbac
1fa30 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e k must not do an
1fa40 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c ything that will
1fa50 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 modify.** the d
1fa60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1fa70 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1fa80 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
1fa90 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 dler..** Note th
1faa0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
1fab0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
1fac0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
1fad0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
1fae0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1faf0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
1fb00 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
1fb10 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
1fb20 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f agraph..**.*/.vo
1fb30 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 id sqlite3_progr
1fb40 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 ess_handler(sqli
1fb50 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a te3*, int, int(*
1fb60 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 )(void*), void*)
1fb70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1fb80 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 F: Opening A New
1fb90 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
1fba0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 tion.**.** ^Thes
1fbb0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 e routines open
1fbc0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 an SQLite databa
1fbd0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 se file as speci
1fbe0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 fied by the .**
1fbf0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e filename argumen
1fc00 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 t. ^The filename
1fc10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 argument is int
1fc20 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d erpreted as UTF-
1fc30 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 8 for.** sqlite3
1fc40 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
1fc50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e te3_open_v2() an
1fc60 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 d as UTF-16 in t
1fc70 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a he native byte.*
1fc80 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 * order for sqli
1fc90 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 te3_open16(). ^(
1fca0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e A [database conn
1fcb0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 ection] handle i
1fcc0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 s usually.** ret
1fcd0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 urned in *ppDb,
1fce0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 even if an error
1fcf0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e occurs. The on
1fd00 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 ly exception is
1fd10 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 that.** if SQLit
1fd20 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 e is unable to a
1fd30 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 llocate memory t
1fd40 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 o hold the [sqli
1fd50 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 te3] object,.**
1fd60 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 a NULL will be w
1fd70 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 ritten into *ppD
1fd80 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 b instead of a p
1fd90 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
1fda0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 qlite3].** objec
1fdb0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 t.)^ ^(If the da
1fdc0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
1fdd0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 (and/or created
1fde0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 ) successfully,
1fdf0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f then.** [SQLITE_
1fe00 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e OK] is returned.
1fe10 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b Otherwise an [
1fe20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 error code] is r
1fe30 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a eturned.)^ ^The.
1fe40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
1fe50 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 sg()] or [sqlite
1fe60 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 3_errmsg16()] ro
1fe70 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 utines can be us
1fe80 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 ed to obtain.**
1fe90 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 an English langu
1fea0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 age description
1feb0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c of the error fol
1fec0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 lowing a failure
1fed0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 of any.** of th
1fee0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
1fef0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
1ff00 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e ^The default en
1ff10 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 coding for the d
1ff20 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 atabase will be
1ff30 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 UTF-8 if.** sqli
1ff40 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
1ff50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1ff60 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a is called and.**
1ff70 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e UTF-16 in the n
1ff80 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
1ff90 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e if sqlite3_open
1ffa0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 16() is used..**
1ffb0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e .** Whether or n
1ffc0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 ot an error occu
1ffd0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 rs when it is op
1ffe0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a ened, resources.
1fff0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
20000 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
20010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
20020 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 dle should be re
20030 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 leased by.** pas
20040 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
20050 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 te3_close()] whe
20060 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 n it is no longe
20070 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a r required..**.*
20080 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 * The sqlite3_op
20090 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 en_v2() interfac
200a0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c e works like sql
200b0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 ite3_open().** e
200c0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 xcept that it ac
200d0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 cepts two additi
200e0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 onal parameters
200f0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 for additional c
20100 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 ontrol.** over t
20110 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
20120 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 connection. ^(T
20130 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
20140 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 er to.** sqlite3
20150 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 _open_v2() can t
20160 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 ake one of.** th
20170 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 e following thre
20180 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e e values, option
20190 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 ally combined wi
201a0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 th the .** [SQLI
201b0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
201c0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 , [SQLITE_OPEN_F
201d0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 ULLMUTEX], [SQLI
201e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
201f0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 CHE],.** [SQLITE
20200 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
20210 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c HE], and/or [SQL
20220 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c ITE_OPEN_URI] fl
20230 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c ags:)^.**.** <dl
20240 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 >.** ^(<dt>[SQLI
20250 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
20260 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 ]</dt>.** <dd>Th
20270 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
20280 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c ened in read-onl
20290 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 y mode. If the
202a0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f database does no
202b0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 t.** already exi
202c0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 st, an error is
202d0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e returned.</dd>)^
202e0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 .**.** ^(<dt>[SQ
202f0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
20300 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ITE]</dt>.** <dd
20310 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 >The database is
20320 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
20330 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 ing and writing
20340 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 if possible, or
20350 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 reading.** only
20360 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 if the file is w
20370 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 rite protected b
20380 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 y the operating
20390 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 system. In eith
203a0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 er.** case the d
203b0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 atabase must alr
203c0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 eady exist, othe
203d0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 rwise an error i
203e0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
203f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b )^.**.** ^(<dt>[
20400 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
20410 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 WRITE] | [SQLITE
20420 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 _OPEN_CREATE]</d
20430 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
20440 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
20450 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
20460 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 writing, and is
20470 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 created if.** i
20480 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 t does not alrea
20490 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 dy exist. This i
204a0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 s the behavior t
204b0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 hat is always us
204c0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 ed for.** sqlite
204d0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
204e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f ite3_open16().</
204f0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a dd>)^.** </dl>.*
20500 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 *.** If the 3rd
20510 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
20520 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
20530 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 s not one of the
20540 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 .** combinations
20550 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 shown above opt
20560 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 ionally combined
20570 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b with other.** [
20580 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
20590 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 ONLY | SQLITE_OP
205a0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 EN_* bits].** th
205b0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
205c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
205d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c .** ^If the [SQL
205e0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
205f0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 ] flag is set, t
20600 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
20610 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
20620 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 pens in the mult
20630 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 i-thread [thread
20640 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e ing mode] as lon
20650 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d g as the single-
20660 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 thread.** mode h
20670 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 as not been set
20680 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
20690 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 or start-time.
206a0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
206b0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
206c0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 X] flag is set t
206d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
206e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
206f0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 s.** in the seri
20700 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
20710 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 g mode] unless s
20720 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 ingle-thread was
20730 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 .** previously s
20740 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 elected at compi
20750 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
20760 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b -time..** ^The [
20770 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 SQLITE_OPEN_SHAR
20780 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 EDCACHE] flag ca
20790 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 uses the databas
207a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 e connection to
207b0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 be.** eligible t
207c0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 o use [shared ca
207d0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 che mode], regar
207e0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
207f0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a or not shared.*
20800 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c * cache is enabl
20810 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
20820 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 3_enable_shared_
20830 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a cache()]. ^The.
20840 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
20850 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c PRIVATECACHE] fl
20860 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
20870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20880 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 n to not.** part
20890 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 icipate in [shar
208a0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 ed cache mode] e
208b0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 ven if it is ena
208c0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
208d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
208e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
208f0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 n_v2() is the na
20900 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 me of the.** [sq
20910 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
20920 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 t that defines t
20930 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
20940 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 tem interface th
20950 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 at.** the new da
20960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20970 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e n should use. ^
20980 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
20990 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 rameter is.** a
209a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
209b0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 n the default [s
209c0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
209d0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a ct is used..**.*
209e0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
209f0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 me is ":memory:"
20a00 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 , then a private
20a10 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d , temporary in-m
20a20 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a emory database.*
20a30 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 * is created for
20a40 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e the connection.
20a50 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 ^This in-memor
20a60 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 y database will
20a70 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 vanish when.** t
20a80 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
20a90 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 ection is closed
20aa0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
20ab0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 ns of SQLite mig
20ac0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f ht.** make use o
20ad0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 f additional spe
20ae0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 cial filenames t
20af0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 hat begin with t
20b00 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 he ":" character
20b10 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d ..** It is recom
20b20 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e mended that when
20b30 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
20b40 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f name actually do
20b50 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a es begin with.**
20b60 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 a ":" character
20b70 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 you should pref
20b80 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 ix the filename
20b90 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 with a pathname
20ba0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 such as.** "./"
20bb0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 to avoid ambigui
20bc0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ty..**.** ^If th
20bd0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e e filename is an
20be0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 empty string, t
20bf0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 hen a private, t
20c00 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 emporary.** on-d
20c10 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c isk database wil
20c20 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e l be created. ^
20c30 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 This private dat
20c40 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a abase will be.**
20c50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
20c60 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 eleted as soon a
20c70 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
20c80 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
20c90 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 sed..**.** [[URI
20ca0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 filenames in sq
20cb0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c lite3_open()]] <
20cc0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 h3>URI Filenames
20cd0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 </h3>.**.** ^If
20ce0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 [URI filename] i
20cf0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 nterpretation is
20d00 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 enabled, and th
20d10 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
20d20 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 ent.** begins wi
20d30 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e th "file:", then
20d40 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 the filename is
20d50 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
20d60 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 a URI. ^URI.** f
20d70 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 ilename interpre
20d80 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 tation is enable
20d90 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 d if the [SQLITE
20da0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 _OPEN_URI] flag
20db0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 is.** set in the
20dc0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
20dd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
20de0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 _v2(), or if it
20df0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 has.** been enab
20e00 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 led globally usi
20e10 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 ng the [SQLITE_C
20e20 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f ONFIG_URI] optio
20e30 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 n with the.** [s
20e40 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
20e50 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 method or by th
20e60 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 e [SQLITE_USE_UR
20e70 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 I] compile-time
20e80 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 option..** As of
20e90 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
20ea0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 3.7.7, URI filen
20eb0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
20ec0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 on is turned off
20ed0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 .** by default,
20ee0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 but future relea
20ef0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ses of SQLite mi
20f00 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 ght enable URI f
20f10 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 ilename.** inter
20f20 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 pretation by def
20f30 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 ault. See "[URI
20f40 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 filenames]" for
20f50 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 additional.** i
20f60 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
20f70 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 * URI filenames
20f80 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 are parsed accor
20f90 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 ding to RFC 3986
20fa0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f . ^If the URI co
20fb0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 ntains an.** aut
20fc0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 hority, then it
20fd0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 must be either a
20fe0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f n empty string o
20ff0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a r the string .**
21000 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 "localhost". ^I
21010 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 f the authority
21020 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 is not an empty
21030 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c string or "local
21040 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 host", an .** er
21050 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ror is returned
21060 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e to the caller. ^
21070 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d The fragment com
21080 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c ponent of a URI,
21090 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c if .** present,
210a0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a is ignored..**.
210b0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
210c0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 the path compone
210d0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 nt of the URI as
210e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
210f0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 disk file.** wh
21100 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ich contains the
21110 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 database. ^If t
21120 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 he path begins w
21130 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 ith a '/' charac
21140 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 ter, .** then it
21150 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
21160 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 as an absolute p
21170 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 ath. ^If the pat
21180 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e h does not begin
21190 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 .** with a '/'
211a0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 (meaning that th
211b0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 e authority sect
211c0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 ion is omitted f
211d0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 rom the URI).**
211e0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 then the path is
211f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
21200 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e a relative path.
21210 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 .** ^On windows
21220 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 , the first comp
21230 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f onent of an abso
21240 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 lute path .** is
21250 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 a drive specifi
21260 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a cation (e.g. "C:
21270 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 ")..**.** [[core
21280 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d URI query param
21290 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 eters]].** The q
212a0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f uery component o
212b0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 f a URI may cont
212c0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 ain parameters t
212d0 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 hat are interpre
212e0 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 ted.** either by
212f0 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 SQLite itself,
21300 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 or by a [VFS | c
21310 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d ustom VFS implem
21320 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 entation]..** SQ
21330 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 Lite interprets
21340 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 the following th
21350 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 ree query parame
21360 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ters:.**.** <ul>
21370 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 .** <li> <b>vf
21380 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 s</b>: ^The "vfs
21390 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 " parameter may
213a0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 be used to speci
213b0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a fy the name of.*
213c0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 * a VFS obje
213d0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 ct that provides
213e0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
213f0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
21400 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 that should.**
21410 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 be used to ac
21420 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
21430 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 e file on disk.
21440 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ^If this option
21450 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 is set to.**
21460 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
21470 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
21480 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
21490 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 ^Specifying an
214a0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 unknown.** V
214b0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 FS is an error.
214c0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
214d0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e _v2() is used an
214e0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e d the vfs option
214f0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 is.** prese
21500 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 nt, then the VFS
21510 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
21520 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 e option takes p
21530 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a recedence over.*
21540 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 * the value
21550 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f passed as the fo
21560 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
21570 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
21580 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 2()..**.** <li
21590 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e > <b>mode</b>: ^
215a0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 (The mode parame
215b0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 ter may be set t
215c0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 o either "ro", "
215d0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 rw",.** "rwc
215e0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 ", or "memory".
215f0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 Attempting to se
21600 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 t it to any othe
21610 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 r value is.**
21620 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a an error)^. .*
21630 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 * ^If "ro" i
21640 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 s specified, the
21650 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
21660 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
21670 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 d-only .** a
21680 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 ccess, just as i
21690 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
216a0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 EN_READONLY] fla
216b0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 g had been set i
216c0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 n the .** th
216d0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
216e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
216f0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 ). ^If the mode
21700 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
21710 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 .** "rw", t
21720 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
21730 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
21740 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e ead-write (but n
21750 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 ot create) .**
21760 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 access, as if
21770 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
21780 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 DWRITE (but not
21790 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
217a0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 TE) had .**
217b0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 been set. ^Value
217c0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 "rwc" is equiva
217d0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
217e0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c both .** SQL
217f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
21800 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 TE and SQLITE_OP
21810 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 EN_CREATE. ^If
21820 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 the mode option
21830 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f is.** set to
21840 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 "memory" then a
21850 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 pure [in-memory
21860 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 database] that
21870 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 never reads.**
21880 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f or writes fro
21890 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 m disk is used.
218a0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 ^It is an error
218b0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c to specify a val
218c0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 ue for.** th
218d0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 e mode parameter
218e0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 that is less re
218f0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 strictive than t
21900 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 hat specified by
21910 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 .** the flag
21920 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 s passed in the
21930 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
21940 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
21950 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c v2()..**.** <l
21960 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a i> <b>cache</b>:
21970 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 ^The cache para
21980 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
21990 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 to either "shar
219a0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 ed" or.** "p
219b0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e rivate". ^Settin
219c0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 g it to "shared"
219d0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
219e0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a o setting the.**
219f0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
21a00 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 _SHAREDCACHE bit
21a10 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 in the flags ar
21a20 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f gument passed to
21a30 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f .** sqlite3_
21a40 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 open_v2(). ^Sett
21a50 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 ing the cache pa
21a60 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 rameter to "priv
21a70 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 ate" is .**
21a80 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
21a90 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 tting the SQLITE
21aa0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
21ab0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e HE bit..** ^
21ac0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
21ad0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 v2() is used and
21ae0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 the "cache" par
21af0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e ameter is presen
21b00 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 t in.** a UR
21b10 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 I filename, its
21b20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 value overrides
21b30 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 any behavior req
21b40 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e uested by settin
21b50 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f g.** SQLITE_
21b60 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
21b70 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e E or SQLITE_OPEN
21b80 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 _SHAREDCACHE fla
21b90 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a g..** </ul>.**.*
21ba0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e * ^Specifying an
21bb0 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 unknown paramet
21bc0 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 er in the query
21bd0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
21be0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 RI is not an.**
21bf0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 error. Future v
21c00 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
21c10 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 e might understa
21c20 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 nd additional qu
21c30 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ery.** parameter
21c40 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 s. See "[query
21c50 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 parameters with
21c60 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 special meaning
21c70 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a to SQLite]" for.
21c80 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e ** additional in
21c90 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
21ca0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 [[URI filename
21cb0 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 examples]] <h3>U
21cc0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
21cd0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 ples</h3>.**.**
21ce0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 <table border="1
21cf0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 " align=center c
21d00 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a ellpadding=5>.**
21d10 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 <tr><th> URI fi
21d20 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 lenames <th> Res
21d30 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ults.** <tr><td>
21d40 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 file:data.db <t
21d50 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
21d60 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
21d70 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
21d80 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
21d90 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
21da0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 le:/home/fred/da
21db0 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 ta.db<br>.**
21dc0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f file:///ho
21dd0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 me/fred/data.db
21de0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <br> .**
21df0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f file://localho
21e00 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 st/home/fred/dat
21e10 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a a.db <br> <td> .
21e20 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
21e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
21e40 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
21e50 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e ata.db"..** <tr>
21e60 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b <td> file://dark
21e70 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 star/home/fred/d
21e80 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 ata.db <td> .**
21e90 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
21ea0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 r. "darkstar" is
21eb0 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 not a recognize
21ec0 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 d authority..**
21ed0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 <tr><td style="w
21ee0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 hite-space:nowra
21ef0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 p"> .**
21f00 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 file:///C:/Docu
21f10 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 ments%20and%20Se
21f20 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b ttings/fred/Desk
21f30 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 top/data.db.**
21f40 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 <td> Windows
21f50 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 only: Open the f
21f60 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e ile "data.db" on
21f70 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 fred's desktop
21f80 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 on drive.**
21f90 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 C:. Note th
21fa0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 at the %20 escap
21fb0 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d ing in this exam
21fc0 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 ple is not stric
21fd0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 tly .**
21fe0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 necessary - spa
21ff0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 ce characters ca
22000 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 n be used litera
22010 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 lly.**
22020 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 in URI filenames
22030 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
22040 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
22050 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 ro&cache=private
22060 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
22070 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 Open file "da
22080 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 ta.db" in the cu
22090 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 rrent directory
220a0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 for read-only ac
220b0 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 cess..**
220c0 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 Regardless of
220d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 whether or not s
220e0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 hared-cache mode
220f0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a is enabled by.*
22100 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 * defau
22110 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 lt, use a privat
22120 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e e cache..** <tr>
22130 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
22140 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 fred/data.db?vfs
22150 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 =unix-nolock <td
22160 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 >.** Op
22170 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 en file "/home/f
22180 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 red/data.db". Us
22190 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 e the special VF
221a0 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e S "unix-nolock".
221b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
221c0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 e:data.db?mode=r
221d0 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a eadonly <td> .**
221e0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
221f0 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 or. "readonly" i
22200 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 s not a valid op
22210 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f tion for the "mo
22220 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a de" parameter..*
22230 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a * </table>.**.**
22240 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 ^URI hexadecima
22250 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 l escape sequenc
22260 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 es (%HH) are sup
22270 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 ported within th
22280 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 e path and.** qu
22290 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
222a0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 f a URI. A hexad
222b0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
222c0 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 quence consists
222d0 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 of a.** percent
222e0 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c sign - "%" - fol
222f0 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 lowed by exactly
22300 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c two hexadecimal
22310 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 digits .** spec
22320 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 ifying an octet
22330 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 value. ^Before t
22340 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 he path or query
22350 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 components of a
22360 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
22370 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
22380 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 , they are encod
22390 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 ed using UTF-8 a
223a0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 nd all .** hexad
223b0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 ecimal escape se
223c0 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 quences replaced
223d0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 by a single byt
223e0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
223f0 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e .** correspondin
22400 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 g octet. If this
22410 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 process generat
22420 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 es an invalid UT
22430 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a F-8 encoding,.**
22440 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
22450 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
22460 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
22470 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 dows users:</b>
22480 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 The encoding us
22490 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e ed for the filen
224a0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
224b0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 of sqlite3_open(
224c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
224d0 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 en_v2() must be
224e0 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 UTF-8, not whate
224f0 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 ver.** codepage
22500 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 is currently def
22510 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 ined. Filenames
22520 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 containing inte
22530 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 rnational.** cha
22540 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 racters must be
22550 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 converted to UTF
22560 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 -8 prior to pass
22570 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a ing them into.**
22580 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
22590 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
225a0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e v2()..**.** <b>N
225b0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 ote to Windows R
225c0 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 untime users:</b
225d0 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 > The temporary
225e0 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 directory must
225f0 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 be set.** prior
22600 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 to calling sqlit
22610 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
22620 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
22630 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 Otherwise, vari
22640 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 ous.** features
22650 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 that require the
22660 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 use of temporar
22670 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c y files may fail
22680 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
22690 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f : [sqlite3_temp_
226a0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e directory].*/.in
226b0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a t sqlite3_open(.
226c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
226d0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
226e0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
226f0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
22700 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 te3 **ppDb
22710 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
22720 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
22730 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f );.int sqlite3_o
22740 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 pen16(. const v
22750 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 oid *filename,
22760 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
22770 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a ename (UTF-16) *
22780 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 /. sqlite3 **pp
22790 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f Db /* O
227a0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 UT: SQLite db ha
227b0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 ndle */.);.int s
227c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a qlite3_open_v2(.
227d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 const char *fi
227e0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
227f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
22800 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 UTF-8) */. sqli
22810 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 te3 **ppDb,
22820 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 /* OUT: SQLi
22830 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a te db handle */.
22840 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 int flags,
22850 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 /* Fla
22860 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 gs */. const ch
22870 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 ar *zVfs
22880 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d /* Name of VFS m
22890 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a odule to use */.
228a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
228b0 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 EF: Obtain Value
228c0 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 s For URI Parame
228d0 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ters.**.** These
228e0 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 are utility rou
228f0 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f tines, useful to
22900 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
22910 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b ions, that check
22920 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 .** to see if a
22930 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 database file wa
22940 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e s a URI that con
22950 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 tained a specifi
22960 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 c query .** para
22970 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f meter, and if so
22980 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c obtains the val
22990 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 ue of that query
229a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a parameter..**.*
229b0 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 * If F is the da
229c0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
229d0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 pointer passed i
229e0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 nto the xOpen()
229f0 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 method of .** a
22a00 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
22a10 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 on when the flag
22a20 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 s parameter to x
22a30 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f Open() has one o
22a40 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 r .** more of th
22a50 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
22a60 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f RI] or [SQLITE_O
22a70 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 PEN_MAIN_DB] bit
22a80 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 s set and.** P i
22a90 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
22aa0 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 e query paramete
22ab0 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 r, then.** sqlit
22ac0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
22ad0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 (F,P) returns th
22ae0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 e value of the P
22af0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 .** parameter if
22b00 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 it exists or a
22b10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
22b20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 P does not appea
22b30 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 r as a .** query
22b40 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e parameter on F.
22b50 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 If P is a quer
22b60 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 y parameter of F
22b70 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 .** has no expli
22b80 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 cit value, then
22b90 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
22ba0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
22bb0 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ns.** a pointer
22bc0 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
22bd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ng..**.** The sq
22be0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
22bf0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
22c00 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 assumes that P
22c10 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 is a boolean.**
22c20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
22c30 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f turns true (1) o
22c40 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f r false (0) acco
22c50 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c rding to the val
22c60 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 ue.** of P. The
22c70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
22c80 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
22c90 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ine returns true
22ca0 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 (1) if the.** v
22cb0 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 alue of query pa
22cc0 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
22cd0 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 of "yes", "true
22ce0 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e ", or "on" in an
22cf0 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 y.** case or if
22d00 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
22d10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f with a non-zero
22d20 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a number. The .*
22d30 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
22d40 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
22d50 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 tines returns fa
22d60 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 lse (0) if the v
22d70 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 alue of.** query
22d80 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
22d90 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 one of "no", "fa
22da0 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 lse", or "off" i
22db0 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a n any case or.**
22dc0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
22dd0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 gins with a nume
22de0 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 ric zero. If P
22df0 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a is not a query.*
22e00 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 * parameter on F
22e10 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
22e20 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f of P is does no
22e30 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 t match any of t
22e40 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 he.** above, the
22e50 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f n sqlite3_uri_bo
22e60 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
22e70 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a urns (B!=0)..**.
22e80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 ** The sqlite3_u
22e90 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 ri_int64(F,P,D)
22ea0 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 routine converts
22eb0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
22ec0 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 into a.** 64-bit
22ed0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 signed integer
22ee0 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 and returns that
22ef0 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 integer, or D i
22f00 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 f P does not.**
22f10 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 exist. If the v
22f20 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d alue of P is som
22f30 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 ething other tha
22f40 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 n an integer, th
22f50 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 en.** zero is re
22f60 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 turned..** .** I
22f70 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f f F is a NULL po
22f80 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 inter, then sqli
22f90 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
22fa0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e r(F,P) returns N
22fb0 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 ULL and.** sqlit
22fc0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
22fd0 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e ,P,B) returns B.
22fe0 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 If F is not a
22ff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
23000 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 .** is not a dat
23010 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e abase file pathn
23020 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 ame pointer that
23030 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 SQLite passed i
23040 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a nto the xOpen.**
23050 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 VFS method, the
23060 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
23070 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 f this routine i
23080 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
23090 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 probably.** unde
230a0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 sirable..*/.cons
230b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
230c0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f uri_parameter(co
230d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
230e0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ame, const char
230f0 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 *zParam);.int sq
23100 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
23110 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 n(const char *zF
23120 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ile, const char
23130 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 *zParam, int bDe
23140 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f fault);.sqlite3_
23150 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 int64 sqlite3_ur
23160 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 i_int64(const ch
23170 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a ar*, const char*
23180 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
23190 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ;.../*.** CAPI3R
231a0 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 EF: Error Codes
231b0 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a And Messages.**.
231c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
231d0 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 errcode() interf
231e0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ace returns the
231f0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 numeric [result
23200 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
23210 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
23220 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 e] for the most
23230 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 recent failed sq
23240 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c lite3_* API call
23250 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
23260 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 ith a [database
23270 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 connection]. If
23280 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c a prior API call
23290 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 failed.** but t
232a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
232b0 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 PI call succeede
232c0 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 d, the return va
232d0 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 lue from.** sqli
232e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
232f0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 undefined. ^Th
23300 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 e sqlite3_extend
23310 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 ed_errcode().**
23320 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 interface is the
23330 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 same except tha
23340 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 t it always retu
23350 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 rns the .** [ext
23360 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
23370 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 e] even when ext
23380 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
23390 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c es are.** disabl
233a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
233b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 qlite3_errmsg()
233c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d and sqlite3_errm
233d0 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e sg16() return En
233e0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a glish-language.*
233f0 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 * text that desc
23400 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c ribes the error,
23410 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 as either UTF-8
23420 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 or UTF-16 respe
23430 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 ctively..** ^(Me
23440 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
23450 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
23460 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
23470 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 internally..**
23480 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
23490 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
234a0 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 worry about fre
234b0 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e eing the result.
234c0 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 .** However, the
234d0 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 error string mi
234e0 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 ght be overwritt
234f0 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 en or deallocate
23500 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 d by.** subseque
23510 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 nt calls to othe
23520 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
23530 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a ce functions.)^.
23540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
23550 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 e3_errstr() inte
23560 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
23570 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 e English-langua
23580 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 ge text.** that
23590 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 describes the [r
235a0 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 esult code], as
235b0 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f UTF-8..** ^(Memo
235c0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 ry to hold the e
235d0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
235e0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 ing is managed i
235f0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 nternally.** and
23600 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 must not be fre
23610 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ed by the applic
23620 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 ation)^..**.** W
23630 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a hen the serializ
23640 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
23650 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 de] is in use, i
23660 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a t might be the.*
23670 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 * case that a se
23680 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 cond error occur
23690 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 s on a separate
236a0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 thread in betwee
236b0 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 n.** the time of
236c0 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 the first error
236d0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f and the call to
236e0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
236f0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 s..** When that
23700 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 happens, the sec
23710 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 ond error will b
23720 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 e reported since
23730 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 these.** interf
23740 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f aces always repo
23750 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 rt the most rece
23760 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 nt result. To a
23770 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 void.** this, ea
23780 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 ch thread can ob
23790 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 tain exclusive u
237a0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 se of the [datab
237b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
237c0 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 D.** by invoking
237d0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
237e0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f enter]([sqlite3_
237f0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 db_mutex](D)) be
23800 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a fore beginning.*
23810 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 * to use D and i
23820 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 nvoking [sqlite3
23830 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 _mutex_leave]([s
23840 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d qlite3_db_mutex]
23850 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c (D)) after.** al
23860 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 l calls to the i
23870 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 nterfaces listed
23880 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 here are comple
23890 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e ted..**.** If an
238a0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 interface fails
238b0 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 with SQLITE_MIS
238c0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 USE, that means
238d0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a the interface.**
238e0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 was invoked inc
238f0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 orrectly by the
23900 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e application. In
23910 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a that case, the.
23920 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e ** error code an
23930 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 d message may or
23940 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e may not be set.
23950 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
23960 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
23970 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *db);.int sqlite
23980 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
23990 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
239a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
239b0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 ite3_errmsg(sqli
239c0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 te3*);.const voi
239d0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
239e0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 g16(sqlite3*);.c
239f0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
23a00 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a e3_errstr(int);.
23a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23a20 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f SQL Statement O
23a30 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
23a40 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
23a50 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
23a60 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
23a70 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
23a80 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
23a90 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
23aa0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
23ab0 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 ..** This object
23ac0 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e is variously kn
23ad0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 own as a "prepar
23ae0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 ed statement" or
23af0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 a.** "compiled
23b00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f SQL statement" o
23b10 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 r simply as a "s
23b20 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a tatement"..**.**
23b30 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 The life of a s
23b40 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 tatement object
23b50 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c goes something l
23b60 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 ike this:.**.**
23b70 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 <ol>.** <li> Cre
23b80 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 ate the object u
23b90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 sing [sqlite3_pr
23ba0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 epare_v2()] or a
23bb0 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 related.**
23bc0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c function..** <l
23bd0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
23be0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 o [host paramete
23bf0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 rs] using the sq
23c00 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a lite3_bind_*().*
23c10 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 * interface
23c20 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 s..** <li> Run t
23c30 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e he SQL by callin
23c40 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
23c50 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 )] one or more t
23c60 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 imes..** <li> Re
23c70 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e set the statemen
23c80 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
23c90 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
23ca0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
23cb0 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
23cc0 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
23cd0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
23ce0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
23cf0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
23d00 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
23d10 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 </ol>.**.** Ref
23d20 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 er to documentat
23d30 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 ion on individua
23d40 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 l methods above
23d50 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a for additional.*
23d60 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a * information..*
23d70 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
23d80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 sqlite3_stmt sq
23d90 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a lite3_stmt;../*.
23da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
23db0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a -time Limits.**.
23dc0 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 ** ^(This interf
23dd0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 ace allows the s
23de0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 ize of various c
23df0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 onstructs to be
23e00 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 limited.** on a
23e10 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f connection by co
23e20 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 nnection basis.
23e30 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
23e40 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b eter is the.** [
23e50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
23e60 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 ion] whose limit
23e70 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 is to be set or
23e80 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a queried. The.*
23e90 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
23ea0 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 er is one of the
23eb0 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 [limit categori
23ec0 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 es] that define
23ed0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f a.** class of co
23ee0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 nstructs to be s
23ef0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 ize limited. Th
23f00 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
23f10 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 r is the.** new
23f20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 limit for that c
23f30 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a onstruct.)^.**.*
23f40 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 * ^If the new li
23f50 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 mit is a negativ
23f60 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 e number, the li
23f70 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 mit is unchanged
23f80 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 ..** ^(For each
23f90 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 limit category S
23fa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e QLITE_LIMIT_<i>N
23fb0 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 AME</i> there is
23fc0 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c a .** [limits |
23fd0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
23fe0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d d].** set at com
23ff0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 pile-time by a C
24000 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
24010 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c cro called.** [l
24020 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d imits | SQLITE_M
24030 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e AX_<i>NAME</i>].
24040 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 .** (The "_LIMIT
24050 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 _" in the name i
24060 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d s changed to "_M
24070 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 AX_".))^.** ^Att
24080 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 empts to increas
24090 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 e a limit above
240a0 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 its hard upper b
240b0 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 ound are.** sile
240c0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 ntly truncated t
240d0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 o the hard upper
240e0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 bound..**.** ^R
240f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
24100 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
24110 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 limit was change
24120 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 d, the .** [sqli
24130 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 te3_limit()] int
24140 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
24150 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
24160 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 f the limit..**
24170 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 ^Hence, to find
24180 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
24190 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 e of a limit wit
241a0 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 hout changing it
241b0 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f ,.** simply invo
241c0 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 ke this interfac
241d0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 e with the third
241e0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 parameter set t
241f0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d o -1..**.** Run-
24200 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 time limits are
24210 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
24220 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 in applications
24230 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 that manage.**
24240 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 both their own i
24250 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
24260 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 and also databa
24270 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e ses that are con
24280 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e trolled.** by un
24290 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c trusted external
242a0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 sources. An ex
242b0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f ample applicatio
242c0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 n might be a.**
242d0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 web browser that
242e0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 has its own dat
242f0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 abases for stori
24300 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a ng history and.*
24310 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 * separate datab
24320 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 ases controlled
24330 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 by JavaScript ap
24340 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c plications downl
24350 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 oaded.** off the
24360 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 Internet. The
24370 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 internal databas
24380 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 es can be given
24390 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 the.** large, de
243a0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 fault limits. D
243b0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 atabases managed
243c0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 by external sou
243d0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 rces can.** be g
243e0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 iven much smalle
243f0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 r limits designe
24400 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 d to prevent a d
24410 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 enial of service
24420 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 .** attack. Dev
24430 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c elopers might al
24440 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 so want to use t
24450 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f he [sqlite3_set_
24460 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a authorizer()].**
24470 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 interface to fu
24480 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e rther control un
24490 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 trusted SQL. Th
244a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 e size of the da
244b0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 tabase.** create
244c0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 d by an untruste
244d0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 d script can be
244e0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 contained using
244f0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 the.** [max_page
24500 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d _count] [PRAGMA]
24510 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d ..**.** New run-
24520 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 time limit categ
24530 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 ories may be add
24540 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
24550 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 eases..*/.int sq
24560 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 lite3_limit(sqli
24570 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e te3*, int id, in
24580 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a t newVal);../*.*
24590 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
245a0 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 Time Limit Categ
245b0 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ories.** KEYWORD
245c0 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f S: {limit catego
245d0 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 ry} {*limit cate
245e0 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 gories}.**.** Th
245f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 ese constants de
24600 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 fine various per
24610 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a formance limits.
24620 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c ** that can be l
24630 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 owered at run-ti
24640 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 me using [sqlite
24650 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 3_limit()]..** T
24660 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 he synopsis of t
24670 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 he meanings of t
24680 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 he various limit
24690 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 s is shown below
246a0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 ..** Additional
246b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 information is a
246c0 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d vailable at [lim
246d0 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 its | Limits in
246e0 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c SQLite]..**.** <
246f0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
24700 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e LIMIT_LENGTH]] ^
24710 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
24720 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a T_LENGTH</dt>.**
24730 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
24740 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 size of any str
24750 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 ing or BLOB or t
24760 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 able row, in byt
24770 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 es.<dd>)^.**.**
24780 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 [[SQLITE_LIMIT_S
24790 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 QL_LENGTH]] ^(<d
247a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 t>SQLITE_LIMIT_S
247b0 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a QL_LENGTH</dt>.*
247c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
247d0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 m length of an S
247e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e QL statement, in
247f0 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a bytes.</dd>)^.*
24800 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
24810 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c MIT_COLUMN]] ^(<
24820 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
24830 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c COLUMN</dt>.** <
24840 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
24850 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
24860 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 in a table defi
24870 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 nition or in the
24880 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f .** result set o
24890 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 f a [SELECT] or
248a0 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 the maximum numb
248b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
248c0 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 an index.** or
248d0 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f in an ORDER BY o
248e0 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 r GROUP BY claus
248f0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 e.</dd>)^.**.**
24900 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 [[SQLITE_LIMIT_E
24910 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 XPR_DEPTH]] ^(<d
24920 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 t>SQLITE_LIMIT_E
24930 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a XPR_DEPTH</dt>.*
24940 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
24950 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 m depth of the p
24960 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 arse tree on any
24970 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 expression.</dd
24980 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
24990 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
249a0 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 D_SELECT]] ^(<dt
249b0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f >SQLITE_LIMIT_CO
249c0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 MPOUND_SELECT</d
249d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
249e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
249f0 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f terms in a compo
24a00 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 und SELECT state
24a10 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ment.</dd>)^.**.
24a20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
24a30 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 T_VDBE_OP]] ^(<d
24a40 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 t>SQLITE_LIMIT_V
24a50 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c DBE_OP</dt>.** <
24a60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
24a70 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 umber of instruc
24a80 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 tions in a virtu
24a90 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 al machine progr
24aa0 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d am.** used to im
24ab0 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 plement an SQL s
24ac0 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 tatement. This
24ad0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 limit is not cur
24ae0 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 rently.** enforc
24af0 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 ed, though that
24b00 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 might be added i
24b10 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
24b20 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
24b30 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a te.</dd>)^.**.**
24b40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
24b50 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e FUNCTION_ARG]] ^
24b60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
24b70 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f T_FUNCTION_ARG</
24b80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
24b90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
24ba0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 arguments on a
24bb0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e function.</dd>)^
24bc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
24bd0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d LIMIT_ATTACHED]]
24be0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
24bf0 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 MIT_ATTACHED</dt
24c00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
24c10 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b imum number of [
24c20 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 ATTACH | attache
24c30 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c d databases].)^<
24c40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
24c50 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 ITE_LIMIT_LIKE_P
24c60 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a ATTERN_LENGTH]].
24c70 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ** ^(<dt>SQLITE_
24c80 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
24c90 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a RN_LENGTH</dt>.*
24ca0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
24cb0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 m length of the
24cc0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 pattern argument
24cd0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f to the [LIKE] o
24ce0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 r.** [GLOB] oper
24cf0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ators.</dd>)^.**
24d00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
24d10 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
24d20 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 ER]].** ^(<dt>SQ
24d30 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 LITE_LIMIT_VARIA
24d40 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a BLE_NUMBER</dt>.
24d50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
24d60 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 um index number
24d70 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 of any [paramete
24d80 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 r] in an SQL sta
24d90 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 tement.)^.**.**
24da0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 [[SQLITE_LIMIT_T
24db0 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e RIGGER_DEPTH]] ^
24dc0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
24dd0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c T_TRIGGER_DEPTH<
24de0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
24df0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 maximum depth of
24e00 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 recursion for t
24e10 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a riggers.</dd>)^.
24e20 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
24e30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
24e40 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
24e50 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
24e60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
24e70 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
24e80 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
24e90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
24ea0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
24eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
24ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
24ed0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
24ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
24ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
24f00 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
24f10 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
24f20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
24f30 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
24f40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24f50 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
24f60 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
24f70 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
24f80 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
24f90 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
24fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24fb0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
24fc0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
24fd0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
24fe0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
24ff0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
25000 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
25010 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
25020 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
25030 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
25040 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 10../*.** CA
25050 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e PI3REF: Compilin
25060 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 g An SQL Stateme
25070 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 nt.** KEYWORDS:
25080 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 {SQL statement c
25090 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 ompiler}.**.** T
250a0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c o execute an SQL
250b0 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 query, it must
250c0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
250d0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
250e0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
250f0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
25100 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a routines..**.**
25110 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
25120 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 ent, "db", is a
25130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
25140 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 tion] obtained f
25150 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 rom a.** prior s
25160 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 uccessful call t
25170 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
25180 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
25190 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 n_v2()] or.** [s
251a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
251b0 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 . The database
251c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 connection must
251d0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c not have been cl
251e0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 osed..**.** The
251f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c second argument,
25200 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 "zSql", is the
25210 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 statement to be
25220 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 compiled, encode
25230 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 d.** as either U
25240 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 TF-8 or UTF-16.
25250 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 The sqlite3_pre
25260 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 pare() and sqlit
25270 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a e3_prepare_v2().
25280 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 ** interfaces us
25290 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c e UTF-8, and sql
252a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
252b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
252c0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 pare16_v2().** u
252d0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
252e0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 ^If the nByte a
252f0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 rgument is less
25300 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 than zero, then
25310 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 zSql is read up
25320 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 to the.** first
25330 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
25340 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f ^If nByte is no
25350 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e n-negative, then
25360 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d it is the maxim
25370 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 um.** number of
25380 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d bytes read from
25390 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 zSql. ^When nB
253a0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 yte is non-negat
253b0 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c ive, the.** zSql
253c0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 string ends at
253d0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 either the first
253e0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 '\000' or '\u00
253f0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 00' character or
25400 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 .** the nByte-th
25410 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 byte, whichever
25420 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 comes first. If
25430 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
25440 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 s.** that the su
25450 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 pplied string is
25460 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c nul-terminated,
25470 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 then there is a
25480 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 small.** perfor
25490 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 mance advantage
254a0 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 to be gained by
254b0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
254c0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
254d0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 ** is equal to t
254e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
254f0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
25500 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
25510 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
25520 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 ul-terminator by
25530 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65 tes as this save
25540 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 s SQLite from ha
25550 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 ving to.** make
25560 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e a copy of the in
25570 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a put string..**.*
25580 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 * ^If pzTail is
25590 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 not NULL then *p
255a0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f zTail is made to
255b0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 point to the fi
255c0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 rst byte.** past
255d0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
255e0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d first SQL statem
255f0 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 ent in zSql. Th
25600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c ese routines onl
25610 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 y.** compile the
25620 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 first statement
25630 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a in zSql, so *pz
25640 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 Tail is left poi
25650 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 nting to.** what
25660 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 remains uncompi
25670 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 led..**.** ^*ppS
25680 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e tmt is left poin
25690 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c ting to a compil
256a0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ed [prepared sta
256b0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e tement] that can
256c0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 be.** executed
256d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 using [sqlite3_s
256e0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 tep()]. ^If the
256f0 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 re is an error,
25700 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a *ppStmt is set.*
25710 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 * to NULL. ^If
25720 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 the input text c
25730 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 ontains no SQL (
25740 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 if the input is
25750 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 an empty.** stri
25760 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 ng or a comment)
25770 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 then *ppStmt is
25780 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a set to NULL..**
25790 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f The calling pro
257a0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e cedure is respon
257b0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 sible for deleti
257c0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a ng the compiled.
257d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
257e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
257f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 finalize()] afte
25800 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 r it has finishe
25810 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 d with it..** pp
25820 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 Stmt may not be
25830 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 NULL..**.** ^On
25840 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c success, the sql
25850 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 ite3_prepare() f
25860 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 amily of routine
25870 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 s return [SQLITE
25880 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 _OK];.** otherwi
25890 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
258a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a e] is returned..
258b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
258c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 3_prepare_v2() a
258d0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
258e0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 re16_v2() interf
258f0 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f aces are.** reco
25900 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 mmended for all
25910 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 new programs. Th
25920 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 e two older inte
25930 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69 rfaces are retai
25940 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 ned.** for backw
25950 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
25960 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 ty, but their us
25970 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 e is discouraged
25980 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 ..** ^In the "v2
25990 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 " interfaces, th
259a0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
259b0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 ment.** that is
259c0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 returned (the [s
259d0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
259e0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 ect) contains a
259f0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f copy of the.** o
25a00 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 riginal SQL text
25a10 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68 . This causes th
25a20 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 e [sqlite3_step(
25a30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a )] interface to.
25a40 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72 ** behave differ
25a50 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 ently in three w
25a60 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a ays:.**.** <ol>.
25a70 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 ** <li>.** ^If t
25a80 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 he database sche
25a90 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 ma changes, inst
25aa0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 ead of returning
25ab0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d [SQLITE_SCHEMA]
25ac0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 as it.** always
25ad0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 used to do, [sq
25ae0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 lite3_step()] wi
25af0 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
25b00 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 recompile the S
25b10 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 QL.** statement
25b20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 and try to run i
25b30 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 t again. As many
25b40 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f as [SQLITE_MAX_
25b50 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a SCHEMA_RETRY].**
25b60 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 retries will oc
25b70 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 cur before sqlit
25b80 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 e3_step() gives
25b90 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 up and returns a
25ba0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 n error..** </li
25bb0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 >.**.** <li>.**
25bc0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f ^When an error o
25bd0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f ccurs, [sqlite3_
25be0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 step()] will ret
25bf0 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 urn one of the d
25c00 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f etailed.** [erro
25c10 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 r codes] or [ext
25c20 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
25c30 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 s]. ^The legacy
25c40 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 behavior was th
25c50 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 at.** [sqlite3_s
25c60 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c tep()] would onl
25c70 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 y return a gener
25c80 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ic [SQLITE_ERROR
25c90 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a ] result code.**
25ca0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 and the applica
25cb0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 tion would have
25cc0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 to make a second
25cd0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
25ce0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 3_reset()].** in
25cf0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 order to find t
25d00 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 he underlying ca
25d10 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c use of the probl
25d20 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 em. With the "v2
25d30 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 " prepare.** int
25d40 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 erfaces, the und
25d50 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 erlying reason f
25d60 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 or the error is
25d70 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 returned immedia
25d80 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a tely..** </li>.*
25d90 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 *.** <li>.** ^If
25da0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61 the specific va
25db0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 lue bound to [pa
25dc0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 rameter | host p
25dd0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
25de0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 .** WHERE claus
25df0 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 e might influenc
25e00 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 e the choice of
25e10 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 query plan for a
25e20 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 statement,.** t
25e30 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e hen the statemen
25e40 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 t will be automa
25e50 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
25e60 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 ed, as if there
25e70 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 had been .** a s
25e80 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e chema change, on
25e90 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c the first [sql
25ea0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c ite3_step()] cal
25eb0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 l following any
25ec0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 change.** to the
25ed0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 [sqlite3_bind_t
25ee0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 ext | bindings]
25ef0 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 of that [paramet
25f00 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 er]. .** ^The sp
25f10 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 ecific value of
25f20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 WHERE-clause [pa
25f30 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 rameter] might i
25f40 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a nfluence the .**
25f50 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 choice of query
25f60 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 plan if the par
25f70 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 ameter is the le
25f80 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 ft-hand side of
25f90 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b a [LIKE].** or [
25fa0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f GLOB] operator o
25fb0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 r if the paramet
25fc0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 er is compared t
25fd0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c o an indexed col
25fe0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b umn.** and the [
25ff0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
26000 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AT3] compile-tim
26010 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 e option is enab
26020 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a led..** </li>.**
26030 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 </ol>.*/.int sq
26040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 lite3_prepare(.
26050 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
26060 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
26070 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
26080 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
26090 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
260a0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 statement, UTF-8
260b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
260c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
260d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
260e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
260f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
26100 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
26110 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
26120 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
26130 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
26140 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
26150 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
26160 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
26170 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 f zSql */.);.int
26180 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
26190 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
261a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
261b0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
261c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
261d0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
261e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
261f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
26200 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
26210 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
26220 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
26230 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
26240 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
26250 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
26260 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
26270 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
26280 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
26290 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
262a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
262b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
262c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 );.int sqlite3_p
262d0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
262e0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
262f0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
26300 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
26310 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
26320 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
26330 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
26340 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
26350 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
26360 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
26370 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
26380 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
26390 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
263a0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
263b0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
263c0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
263d0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
263e0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
263f0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
26400 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ql */.);.int sql
26410 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
26420 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
26430 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
26440 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
26450 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
26460 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
26470 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
26480 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
26490 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
264a0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
264b0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
264c0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
264d0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
264e0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
264f0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
26500 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
26510 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
26520 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
26530 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
26540 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
26550 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
26560 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 F: Retrieving St
26570 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a atement SQL.**.*
26580 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 * ^This interfac
26590 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
265a0 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 retrieve a save
265b0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 d copy of the or
265c0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 iginal.** SQL te
265d0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 xt used to creat
265e0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 e a [prepared st
265f0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 atement] if that
26600 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a statement was.*
26610 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 * compiled using
26620 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
26630 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
26640 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
26650 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 re16_v2()]..*/.c
26660 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
26670 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 e3_sql(sqlite3_s
26680 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
26690 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
266a0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 termine If An SQ
266b0 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 L Statement Writ
266c0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a es The Database.
266d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
266e0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
266f0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (X) interface re
26700 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d turns true (non-
26710 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 zero) if.** and
26720 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 only if the [pre
26730 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
26740 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 X makes no dire
26750 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a ct changes to.**
26760 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
26770 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
26780 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 e..**.** Note th
26790 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d at [application-
267a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
267b0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 tions] or.** [vi
267c0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 rtual tables] mi
267d0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 ght change the d
267e0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 atabase indirect
267f0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 ly as a side eff
26800 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 ect. .** ^(For
26810 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 example, if an a
26820 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e pplication defin
26830 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 es a function "e
26840 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 val()" that .**
26850 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 calls [sqlite3_e
26860 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 xec()], then the
26870 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 following SQL s
26880 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a tatement would.*
26890 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 * change the dat
268a0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 abase file throu
268b0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a gh side-effects:
268c0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
268d0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 te><pre>.** S
268e0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 ELECT eval('DELE
268f0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f TE FROM t1') FRO
26900 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c M t2;.** </pre><
26910 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
26920 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 ** But because t
26930 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 he [SELECT] stat
26940 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 ement does not c
26950 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
26960 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 se file.** direc
26970 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d tly, sqlite3_stm
26980 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 t_readonly() wou
26990 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 ld still return
269a0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 true.)^.**.** ^T
269b0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
269c0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 ol statements su
269d0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b ch as [BEGIN], [
269e0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 COMMIT], [ROLLBA
269f0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 CK],.** [SAVEPOI
26a00 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 NT], and [RELEAS
26a10 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 E] cause sqlite3
26a20 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
26a30 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c to return true,
26a40 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 .** since the st
26a50 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c atements themsel
26a60 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 ves do not actua
26a70 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 lly modify the d
26a80 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 atabase but.** r
26a90 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 ather they contr
26aa0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 ol the timing of
26ab0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 when other stat
26ac0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 ements modify th
26ad0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 e .** database.
26ae0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 ^The [ATTACH] a
26af0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 nd [DETACH] stat
26b00 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 ements also caus
26b10 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d e.** sqlite3_stm
26b20 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 t_readonly() to
26b30 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 return true sinc
26b40 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 e, while those s
26b50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 tatements.** cha
26b60 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 nge the configur
26b70 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 ation of a datab
26b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 ase connection,
26b90 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 they do not make
26ba0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 .** changes to
26bb0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
26bc0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
26bd0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e s on disk..*/.in
26be0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 t sqlite3_stmt_r
26bf0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
26c00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
26c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
26c20 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
26c30 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
26c40 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
26c50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
26c60 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 e3_stmt_busy(S)
26c70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
26c80 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
26c90 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ) if the.** [pre
26ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
26cb0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 S has been step
26cc0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 ped at least onc
26cd0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c e using .** [sql
26ce0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 ite3_step(S)] bu
26cf0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f t has not run to
26d00 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f completion and/
26d10 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 or has not .** b
26d20 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 een reset using
26d30 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 [sqlite3_reset(S
26d40 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 )]. ^The sqlite
26d50 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 3_stmt_busy(S).*
26d60 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 * interface retu
26d70 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 rns false if S i
26d80 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
26d90 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 . If S is not a
26da0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 .** NULL pointe
26db0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 r and is not a p
26dc0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 ointer to a vali
26dd0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
26de0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 ement].** object
26df0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 , then the behav
26e00 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 ior is undefined
26e10 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e and probably un
26e20 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a desirable..**.**
26e30 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
26e40 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 can be used in c
26e50 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 ombination [sqli
26e60 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d te3_next_stmt()]
26e70 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c .** to locate al
26e80 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 l prepared state
26e90 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 ments associated
26ea0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 with a database
26eb0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 .** connection
26ec0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 that are in need
26ed0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e of being reset.
26ee0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 This can be us
26ef0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 ed,.** for examp
26f00 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 le, in diagnosti
26f10 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 c routines to se
26f20 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 arch for prepare
26f30 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 d .** statements
26f40 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e that are holdin
26f50 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 g a transaction
26f60 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c open..*/.int sql
26f70 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 ite3_stmt_busy(s
26f80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
26f90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26fa0 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
26fb0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
26fc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
26fd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
26fe0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
26ff0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
27000 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
27010 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
27020 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
27030 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
27040 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
27050 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
27060 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
27070 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
27080 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
27090 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
270a0 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
270b0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
270c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
270d0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
270e0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
270f0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
27100 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
27110 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
27120 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
27130 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
27140 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
27150 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
27160 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
27170 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
27180 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
27190 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
271a0 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
271b0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
271c0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
271d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
271e0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
271f0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
27200 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
27210 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
27220 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
27230 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
27240 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
27250 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
27260 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 lue..**.** The t
27270 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 erms "protected"
27280 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 and "unprotecte
27290 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 d" refer to whet
272a0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 her or not.** a
272b0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 mutex is held.
272c0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 An internal mute
272d0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 x is held for a
272e0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
272f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
27300 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 t but no mutex i
27310 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e s held for an un
27320 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
27330 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
27340 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 t. If SQLite is
27350 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 compiled to be
27360 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a single-threaded.
27370 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 ** (with [SQLITE
27380 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 _THREADSAFE=0] a
27390 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 nd with [sqlite3
273a0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 _threadsafe()] r
273b0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f eturning 0).** o
273c0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 r if SQLite is r
273d0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 un in one of red
273e0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 uced mutex modes
273f0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [SQLITE_CON
27400 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
27410 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
27420 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
27430 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 .** then there i
27440 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e s no distinction
27450 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 between protect
27460 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 ed and unprotect
27470 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 ed.** sqlite3_va
27480 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 lue objects and
27490 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 they can be used
274a0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 interchangeably
274b0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 . However,.** f
274c0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 or maximum code
274d0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 portability it i
274e0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
274f0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a at applications.
27500 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 ** still make th
27510 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 e distinction be
27520 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 tween protected
27530 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a and unprotected.
27540 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
27550 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 objects even wh
27560 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 en not strictly
27570 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 required..**.**
27580 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
27590 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 ue objects that
275a0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 are passed as pa
275b0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 rameters into th
275c0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
275d0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 ion of [applicat
275e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
275f0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 functions] are p
27600 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 rotected..** ^Th
27610 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 e sqlite3_value
27620 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
27630 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
27640 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
27650 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a s unprotected..*
27660 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 * Unprotected sq
27670 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
27680 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 cts may only be
27690 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 used with.** [sq
276a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
276b0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ue()] and [sqlit
276c0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
276d0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
276e0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 3_value_blob | s
276f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 qlite3_value_typ
27700 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a e()] family of.*
27710 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 * interfaces req
27720 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 uire protected s
27730 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
27740 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 ects..*/.typedef
27750 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 struct Mem sqli
27760 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a te3_value;../*.*
27770 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 * CAPI3REF: SQL
27780 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
27790 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 Object.**.** Th
277a0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 e context in whi
277b0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 ch an SQL functi
277c0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 on executes is s
277d0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 tored in an.** s
277e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
277f0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 bject. ^A point
27800 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 er to an sqlite3
27810 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a _context object.
27820 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 ** is always fir
27830 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
27840 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
27850 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
27860 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c ns]..** The appl
27870 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27880 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 SQL function imp
27890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c lementation will
278a0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f pass this.** po
278b0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e inter through in
278c0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c to calls to [sql
278d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 ite3_result_int
278e0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 | sqlite3_result
278f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
27900 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
27910 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f xt()], [sqlite3_
27920 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a user_data()],.**
27930 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 [sqlite3_contex
27940 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 t_db_handle()],
27950 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 [sqlite3_get_aux
27960 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f data()],.** and/
27970 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f or [sqlite3_set_
27980 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 auxdata()]..*/.t
27990 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
279a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 lite3_context sq
279b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a lite3_context;..
279c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
279d0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 Binding Values T
279e0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 o Prepared State
279f0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 ments.** KEYWORD
27a00 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 S: {host paramet
27a10 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 er} {host parame
27a20 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 ters} {host para
27a30 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b meter name}.** K
27a40 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 EYWORDS: {SQL pa
27a50 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 rameter} {SQL pa
27a60 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d rameters} {param
27a70 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a eter binding}.**
27a80 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c .** ^(In the SQL
27a90 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
27aa0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
27ab0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
27ac0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
27ad0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 ,.** literals ma
27ae0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 y be replaced by
27af0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 a [parameter] t
27b00 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 hat matches one
27b10 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 of following.**
27b20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a templates:.**.**
27b30 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
27b40 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
27b50 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
27b60 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
27b70 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
27b80 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 >.**.** In the t
27b90 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 emplates above,
27ba0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 NNN represents a
27bb0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 n integer litera
27bc0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 l,.** and VVV re
27bd0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 presents an alph
27be0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 anumeric identif
27bf0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c ier.)^ ^The val
27c00 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ues of these.**
27c10 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f parameters (also
27c20 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 called "host pa
27c30 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f rameter names" o
27c40 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 r "SQL parameter
27c50 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
27c60 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
27c70 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
27c80 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
27c90 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 re..**.** ^The f
27ca0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
27cb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
27cc0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
27cd0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
27ce0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
27cf0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
27d00 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
27d10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
27d20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
27d30 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
27d40 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 * ^The second ar
27d50 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
27d60 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 dex of the SQL p
27d70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 arameter to be s
27d80 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 et..** ^The left
27d90 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 most SQL paramet
27da0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
27db0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 of 1. ^When the
27dc0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
27dd0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
27de0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
27df0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
27e00 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
27e10 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
27e20 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
27e30 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
27e40 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 rence..** ^The i
27e50 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 ndex for named p
27e60 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 arameters can be
27e70 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 looked up using
27e80 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
27e90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
27ea0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 index()] API if
27eb0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 desired. ^The i
27ec0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
27ed0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
27ee0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
27ef0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 N..** ^The NNN v
27f00 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
27f10 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
27f20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
27f30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
27f40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
27f50 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
27f60 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
27f70 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 )..**.** ^The th
27f80 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
27f90 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e the value to bin
27fa0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 d to the paramet
27fb0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
27fc0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
27fd0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
27fe0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
27ff0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
28000 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
28010 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 d_blob() is a NU
28020 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
28030 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
28040 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 eter.** is ignor
28050 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 ed and the end r
28060 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d esult is the sam
28070 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e e as sqlite3_bin
28080 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 d_null()..**.**
28090 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
280a0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
280b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
280c0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
280d0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
280e0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
280f0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
28100 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
28110 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
28120 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
28130 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
28140 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
28150 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
28160 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
28170 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
28180 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
28190 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
281a0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 _text16().** is
281b0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
281c0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
281d0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
281e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
281f0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
28200 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
28210 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 r..** If the fou
28220 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
28230 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
28240 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 ob() is negative
28250 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 , then.** the be
28260 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
28270 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e ned..** If a non
28280 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 -negative fourth
28290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
282a0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 ovided to sqlite
282b0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 3_bind_text().**
282c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
282d0 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 _text16() then t
282e0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 hat parameter mu
282f0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
28300 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 ffset.** where t
28310 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
28320 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 r would occur as
28330 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e suming the strin
28340 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 g were NUL.** te
28350 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
28360 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
28370 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f occur at byte o
28380 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e ffsets less than
28390 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f .** the value o
283a0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
283b0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 ameter then the
283c0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
283d0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 value will.** c
283e0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
283f0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c NULs. The resul
28400 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
28410 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e involving strin
28420 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 gs.** with embed
28430 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
28440 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
28450 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
28460 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
28470 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
28480 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e _bind_text(), an
28490 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e d.** sqlite3_bin
284a0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 d_text16() is a
284b0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
284c0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
284d0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
284e0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
284f0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
28500 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
28510 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
28520 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
28530 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
28540 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
28550 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 e call to sqlite
28560 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 3_bind_blob(),.*
28570 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 * sqlite3_bind_t
28580 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 ext(), or sqlite
28590 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
285a0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 fails. .** ^If
285b0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
285c0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
285d0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
285e0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
285f0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
28600 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
28610 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
28620 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
28630 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
28640 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
28650 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
28660 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
28670 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
28680 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
28690 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
286a0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
286b0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
286c0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
286d0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
286e0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
286f0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
28700 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
28710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
28720 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
28730 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
28740 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
28750 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
28760 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
28770 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
28780 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
28790 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
287a0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
287b0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
287c0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
287d0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
287e0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
287f0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
28800 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
28810 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
28820 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
28830 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
28840 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
28850 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
28860 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
28870 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
28880 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
28890 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
288a0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
288b0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 BLOB..**.** ^If
288c0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
288d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
288e0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
288f0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
28900 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
28910 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
28920 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
28930 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
28940 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
28950 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
28960 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
28970 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
28980 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
28990 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
289a0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
289b0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
289c0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
289d0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
289e0 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
289f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
28a00 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
28a10 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
28a20 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
28a30 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
28a40 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
28a50 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
28a60 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
28a70 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
28a80 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
28a90 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
28aa0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
28ab0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
28ac0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
28ad0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
28ae0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
28af0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
28b00 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
28b10 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
28b20 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
28b30 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 g..** ^[SQLITE_R
28b40 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 ANGE] is returne
28b50 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 d if the paramet
28b60 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f er.** index is o
28b70 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b ut of range. ^[
28b80 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 SQLITE_NOMEM] is
28b90 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c returned if mal
28ba0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a loc() fails..**.
28bb0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
28bc0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
28bd0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a eter_count()],.*
28be0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
28bf0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 parameter_name()
28c00 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
28c10 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
28c20 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 ndex()]..*/.int
28c30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
28c40 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
28c50 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
28c60 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
28c70 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 )(void*));.int s
28c80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 qlite3_bind_doub
28c90 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
28ca0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a , int, double);.
28cb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
28cc0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
28cd0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 t*, int, int);.i
28ce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
28cf0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
28d00 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 mt*, int, sqlite
28d10 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 3_int64);.int sq
28d20 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 lite3_bind_null(
28d30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
28d40 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 nt);.int sqlite3
28d50 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
28d60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
28d70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 onst char*, int
28d80 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
28d90 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
28da0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 bind_text16(sqli
28db0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
28dc0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
28dd0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
28de0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
28df0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
28e00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
28e10 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
28e20 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
28e30 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
28e40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
28e50 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
28e60 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
28e70 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
28e80 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ters.**.** ^This
28e90 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
28ea0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
28eb0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
28ec0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
28ed0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
28ee0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
28ef0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
28f00 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
28f10 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
28f20 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
28f30 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
28f40 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
28f50 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
28f60 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
28f70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
28f80 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
28f90 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
28fa0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
28fb0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
28fc0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
28fd0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
28fe0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
28ff0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
29000 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
29010 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
29020 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
29030 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
29040 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
29050 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
29060 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
29070 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
29080 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
29090 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
290a0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
290b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
290c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
290d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
290e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
290f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
29100 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
29110 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
29120 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
29130 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
29140 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
29150 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
29160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29170 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
29180 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a t Parameter.**.*
29190 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
291a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
291b0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(P,N) interfac
291c0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 e returns.** the
291d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 name of the N-t
291e0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 h [SQL parameter
291f0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 ] in the [prepar
29200 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
29210 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 .** ^(SQL parame
29220 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
29230 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
29240 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
29250 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
29260 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
29270 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
29280 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
29290 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
292a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
292b0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
292c0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
292d0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
292e0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
292f0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
29300 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 the name.)^.**
29310 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 ^Parameters of t
29320 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
29330 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
29340 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
29350 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
29360 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 referred to as "
29370 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e nameless" or "an
29380 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
29390 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rs"..**.** ^The
293a0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
293b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
293c0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
293d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c *.** ^If the val
293e0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 ue N is out of r
293f0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e ange or if the N
29400 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 -th parameter is
29410 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 .** nameless, th
29420 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 en NULL is retur
29430 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ned. ^The retur
29440 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a ned string is.**
29450 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 always in UTF-8
29460 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 encoding even i
29470 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 f the named para
29480 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 meter was.** ori
29490 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 ginally specifie
294a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b d as UTF-16 in [
294b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
294c0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 6()] or.** [sqli
294d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
294e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
294f0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
29500 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
29510 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
29520 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
29530 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
29540 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
29550 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
29560 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 ex()]..*/.const
29570 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 char *sqlite3_bi
29580 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
29590 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
295a0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
295b0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
295c0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
295d0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a h A Given Name.*
295e0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
295f0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
29600 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
29610 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
29620 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
29630 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
29640 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
29650 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
29660 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
29670 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
29680 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
29690 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
296a0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
296b0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
296c0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
296d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
296e0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
296f0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
29700 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
29710 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
29720 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
29730 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
29740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
29750 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
29760 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
29770 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
29780 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
29790 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
297a0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
297b0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
297c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
297d0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
297e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
297f0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 arameter_index(s
29800 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f qlite3_stmt*, co
29810 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
29820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29830 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e F: Reset All Bin
29840 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 dings On A Prepa
29850 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a red Statement.**
29860 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f .** ^Contrary to
29870 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f the intuition o
29880 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 f many, [sqlite3
29890 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e _reset()] does n
298a0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 ot reset.** the
298b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
298c0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f ob | bindings] o
298d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
298e0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 atement]..** ^Us
298f0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
29900 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 o reset all host
29910 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e parameters to N
29920 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
29930 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
29940 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
29950 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
29960 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f EF: Number Of Co
29970 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c lumns In A Resul
29980 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 t Set.**.** ^Ret
29990 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
299a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
299b0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
299c0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
299d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
299e0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 nt]. ^This routi
299f0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
29a00 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a pStmt is an SQL.
29a10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ** statement tha
29a20 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 t does not retur
29a30 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d n data (for exam
29a40 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
29a50 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
29a60 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
29a70 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 count()].*/.int
29a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
29a90 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
29aa0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
29ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
29ac0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
29ad0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e sult Set.**.** ^
29ae0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
29af0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
29b00 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
29b10 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
29b20 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
29b30 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
29b40 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 ] statement. ^T
29b50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
29b60 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
29b70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
29b80 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
29b90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
29ba0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
29bb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
29bc0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
29bd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
29be0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
29bf0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
29c00 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 . ^The first pa
29c10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
29c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
29c30 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
29c40 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
29c50 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e CT] statement. ^
29c60 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
29c70 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
29c80 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e olumn number. ^
29c90 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
29ca0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
29cb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
29cc0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
29cd0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
29ce0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
29cf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29d00 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
29d10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
29d20 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
29d30 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
29d40 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
29d50 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
29d60 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
29d70 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
29d80 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
29d90 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
29da0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
29db0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
29dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
29dd0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
29de0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
29df0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
29e00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 .**.** ^If sqlit
29e10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
29e20 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
29e30 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
29e40 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
29e50 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
29e60 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
29e70 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
29e80 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
29e90 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
29ea0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
29eb0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
29ec0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
29ed0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
29ee0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
29ef0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
29f00 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
29f10 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
29f20 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
29f30 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
29f40 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
29f50 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
29f60 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
29f70 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
29f80 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
29f90 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f the next..*/.co
29fa0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
29fb0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 3_column_name(sq
29fc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
29fd0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 N);.const void
29fe0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
29ff0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2a000 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
2a010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2a020 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
2a030 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2a040 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2a050 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
2a060 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
2a070 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
2a080 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
2a090 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
2a0a0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
2a0b0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
2a0c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
2a0d0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
2a0e0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
2a0f0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
2a100 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
2a110 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
2a120 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
2a130 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
2a140 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
2a150 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
2a160 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
2a170 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
2a180 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
2a190 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2a1a0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
2a1b0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
2a1c0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
2a1d0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
2a1e0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
2a1f0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2a200 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
2a210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2a220 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
2a230 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
2a240 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2a250 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2a260 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2a270 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2a280 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2a290 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2a2a0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2a2b0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2a2c0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2a2d0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
2a2e0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
2a2f0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
2a300 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
2a310 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
2a320 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
2a330 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
2a340 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
2a350 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
2a360 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
2a370 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
2a380 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
2a390 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
2a3a0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
2a3b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2a3c0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
2a3d0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2a3e0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
2a3f0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
2a400 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
2a410 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
2a420 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
2a430 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
2a440 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
2a450 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
2a460 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
2a470 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
2a480 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
2a490 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
2a4a0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
2a4b0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
2a4c0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
2a4d0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
2a4e0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
2a4f0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
2a500 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2a510 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
2a520 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
2a530 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
2a540 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
2a550 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
2a560 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
2a570 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
2a580 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
2a590 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
2a5a0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
2a5b0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
2a5c0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
2a5d0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
2a5e0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
2a5f0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
2a600 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
2a610 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
2a620 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
2a630 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
2a640 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
2a650 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
2a660 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
2a670 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
2a680 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
2a690 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
2a6a0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
2a6b0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
2a6c0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
2a6d0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
2a6e0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
2a6f0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
2a700 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2a710 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2a720 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
2a730 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
2a740 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
2a750 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
2a760 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
2a770 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
2a780 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
2a790 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
2a7a0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
2a7b0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
2a7c0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
2a7d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2a7e0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
2a7f0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
2a800 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
2a810 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
2a820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
2a830 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
2a840 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
2a850 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
2a860 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2a870 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
2a880 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2a890 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2a8a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2a8b0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2a8c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2a8d0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2a8e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2a8f0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
2a900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2a910 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
2a920 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2a930 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2a940 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
2a950 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2a960 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2a970 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2a980 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2a990 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2a9a0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2a9b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2a9c0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2a9d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2a9e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a9f0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2aa00 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2aa10 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 Result.**.** ^(T
2aa20 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2aa30 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
2aa40 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2aa50 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
2aa60 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
2aa70 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2aa80 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
2aa90 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
2aaa0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
2aab0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
2aac0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
2aad0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
2aae0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2aaf0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
2ab00 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
2ab10 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
2ab20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
2ab30 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2ab40 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2ab50 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
2ab60 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2ab70 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
2ab80 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2ab90 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
2aba0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2abb0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
2abc0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
2abd0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
2abe0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2abf0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
2ac00 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
2ac10 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
2ac20 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
2ac30 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
2ac40 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
2ac50 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
2ac60 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
2ac70 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
2ac80 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
2ac90 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
2aca0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
2acb0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
2acc0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
2acd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
2ace0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
2acf0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
2ad00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2ad10 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
2ad20 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
2ad30 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
2ad40 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
2ad50 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
2ad60 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
2ad70 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
2ad80 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
2ad90 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
2ada0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
2adb0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
2adc0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
2add0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
2ade0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
2adf0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
2ae00 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
2ae10 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
2ae20 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
2ae30 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
2ae40 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
2ae50 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
2ae60 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
2ae70 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
2ae80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
2ae90 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
2aea0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2aeb0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2aec0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
2aed0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2aee0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2aef0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
2af00 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
2af10 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
2af20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2af30 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
2af40 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
2af50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2af60 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
2af70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2af80 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
2af90 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2afa0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
2afb0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
2afc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2afd0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
2afe0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
2aff0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
2b000 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
2b010 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
2b020 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
2b030 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
2b040 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
2b050 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
2b060 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
2b070 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
2b080 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
2b090 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
2b0a0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
2b0b0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
2b0c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2b0d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2b0e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2b0f0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
2b100 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
2b110 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2b120 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2b130 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
2b140 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
2b150 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
2b160 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2b170 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
2b180 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
2b190 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
2b1a0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
2b1b0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
2b1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
2b1d0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2b1e0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2b1f0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
2b200 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
2b210 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2b220 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
2b230 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
2b240 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
2b250 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
2b260 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2b270 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
2b280 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
2b290 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2b2a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
2b2b0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
2b2c0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
2b2d0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
2b2e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
2b2f0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
2b300 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
2b310 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
2b320 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
2b330 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
2b340 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
2b350 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
2b360 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
2b370 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
2b380 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2b390 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
2b3a0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
2b3b0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
2b3c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
2b3d0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
2b3e0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
2b3f0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 an.** explicit t
2b400 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
2b410 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
2b420 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
2b430 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
2b440 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
2b450 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d ^[SQLITE_DONE] m
2b460 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
2b470 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
2b480 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
2b490 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
2b4a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2b4b0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2b4c0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
2b4d0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
2b4e0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
2b4f0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
2b500 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
2b510 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
2b520 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
2b530 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2b540 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e l state..**.** ^
2b550 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2b560 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
2b570 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
2b580 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
2b590 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
2b5a0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
2b5b0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
2b5c0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
2b5d0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
2b5e0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
2b5f0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
2b600 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
2b610 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
2b620 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
2b630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2b640 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
2b650 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
2b660 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
2b670 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2b680 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
2b690 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
2b6a0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
2b6b0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
2b6c0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
2b6d0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
2b6e0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
2b6f0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
2b700 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
2b710 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
2b720 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
2b730 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2b740 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 errmsg()]..** ^W
2b750 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
2b760 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
2b770 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
2b780 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
2b790 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
2b7a0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
2b7b0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
2b7c0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
2b7d0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
2b7e0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
2b7f0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2b800 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
2b810 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2b820 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 tatement]. ^In
2b830 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2b840 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
2b850 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
2b860 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
2b870 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
2b880 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
2b890 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
2b8a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2b8b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
2b8c0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
2b8d0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
2b8e0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
2b8f0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
2b900 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2b910 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
2b920 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
2b930 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
2b940 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
2b950 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
2b960 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
2b970 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
2b980 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
2b990 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
2b9a0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
2b9b0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2b9c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2b9d0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
2b9e0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
2b9f0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
2ba00 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
2ba10 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 ..**.** For all
2ba20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2ba30 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 te up to and inc
2ba40 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c luding 3.6.23.1,
2ba50 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 a call to.** [s
2ba60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2ba70 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 was required aft
2ba80 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
2ba90 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 ) returned anyth
2baa0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 ing.** other tha
2bab0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 n [SQLITE_ROW] b
2bac0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 efore any subseq
2bad0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 uent invocation
2bae0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 of.** sqlite3_st
2baf0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 ep(). Failure t
2bb00 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 o reset the prep
2bb10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
2bb20 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
2bb30 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 3_reset()] would
2bb40 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 result in an [S
2bb50 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 QLITE_MISUSE] re
2bb60 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c turn from.** sql
2bb70 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 ite3_step(). Bu
2bb80 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 t after version
2bb90 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 3.6.23.1, sqlite
2bba0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
2bbb0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
2bbc0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
2bbd0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
2bbe0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
2bbf0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
2bc00 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
2bc10 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
2bc20 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
2bc30 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
2bc40 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
2bc50 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
2bc60 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
2bc70 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
2bc80 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
2bc90 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
2bca0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
2bcb0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
2bcc0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
2bcd0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
2bce0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
2bcf0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
2bd00 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
2bd10 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
2bd20 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
2bd30 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2bd40 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
2bd50 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
2bd60 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
2bd70 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
2bd80 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
2bd90 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
2bda0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
2bdb0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
2bdc0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
2bdd0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
2bde0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
2bdf0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2be00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2be10 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
2be20 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
2be30 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
2be40 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
2be50 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
2be60 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
2be70 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
2be80 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
2be90 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
2bea0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
2beb0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
2bec0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
2bed0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
2bee0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
2bef0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
2bf00 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
2bf10 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2bf20 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2bf30 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
2bf40 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
2bf50 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
2bf60 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2bf70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2bf80 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
2bf90 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
2bfa0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2bfb0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
2bfc0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
2bfd0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2bfe0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
2bff0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2c000 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
2c010 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2c020 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
2c030 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2c040 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
2c050 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
2c060 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 ult set.**.** ^T
2c070 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2c080 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
2c090 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
2c0a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2c0b0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
2c0c0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2c0d0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
2c0e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2c0f0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
2c100 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2c110 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
2c120 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
2c130 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
2c140 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
2c150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
2c160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2c170 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
2c180 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
2c190 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2c1a0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
2c1b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2c1c0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
2c1d0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
2c1e0 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
2c1f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
2c200 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2c210 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2c220 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
2c230 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2c240 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2c250 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
2c260 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2c270 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2c280 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
2c290 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
2c2a0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
2c2b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2c2c0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2c2d0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
2c2e0 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
2c2f0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
2c300 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
2c310 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
2c320 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
2c330 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
2c340 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
2c350 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
2c360 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
2c370 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
2c380 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2c390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c3a0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 _count()].*/.int
2c3b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2c3c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2c3d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2c3e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
2c3f0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
2c400 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
2c410 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
2c420 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
2c430 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
2c440 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
2c450 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
2c460 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2c470 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
2c480 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
2c490 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
2c4a0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
2c4b0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
2c4c0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
2c4d0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
2c4e0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
2c4f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
2c500 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
2c510 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
2c520 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
2c530 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
2c540 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
2c550 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
2c560 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
2c570 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
2c580 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
2c590 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
2c5a0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
2c5b0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
2c5c0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
2c5d0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
2c5e0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
2c5f0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
2c600 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
2c610 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
2c620 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
2c630 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
2c640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
2c650 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
2c660 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
2c670 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
2c680 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
2c690 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
2c6a0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2c6b0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
2c6c0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
2c6d0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
2c6e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2c6f0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
2c700 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
2c710 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
2c720 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
2c730 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2c740 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
2c750 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
2c760 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
2c770 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2c780 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2c790 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
2c7a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
2c7b0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
2c7c0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
2c7d0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
2c7e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2c7f0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2c800 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2c810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2c820 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2c830 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2c840 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2c850 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2c860 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2c870 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2c880 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2c890 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2c8a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2c8b0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2c8c0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2c8d0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2c8e0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2c8f0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
2c900 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2c910 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2c920 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2c930 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
2c940 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2c950 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
2c960 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
2c970 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2c980 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
2c990 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
2c9a0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2c9b0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
2c9c0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
2c9d0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
2c9e0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
2c9f0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
2ca00 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2ca10 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
2ca20 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
2ca30 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
2ca40 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2ca50 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2ca60 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2ca70 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2ca80 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
2ca90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2caa0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
2cab0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
2cac0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
2cad0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
2cae0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
2caf0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2cb00 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
2cb10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2cb20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2cb30 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
2cb40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2cb50 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
2cb60 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2cb70 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2cb80 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
2cb90 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2cba0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
2cbb0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2cbc0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2cbd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2cbe0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
2cbf0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
2cc00 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
2cc10 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2cc20 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
2cc30 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2cc40 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2cc50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2cc60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2cc70 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
2cc80 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
2cc90 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
2cca0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
2ccb0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
2ccc0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
2ccd0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2cce0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2ccf0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2cd00 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2cd10 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2cd20 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2cd30 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2cd40 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2cd50 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2cd60 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2cd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2cd80 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2cd90 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2cda0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2cdb0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2cdc0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2cdd0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2cde0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2cdf0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2ce00 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2ce10 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2ce20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2ce30 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2ce40 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2ce50 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2ce60 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2ce70 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2ce80 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2ce90 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2cea0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2ceb0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2cec0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2ced0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2cee0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2cef0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2cf00 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2cf10 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2cf20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2cf30 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2cf40 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2cf50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2cf60 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2cf70 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2cf80 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2cf90 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2cfa0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2cfb0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2cfc0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2cfd0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2cfe0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2cff0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2d000 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2d010 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2d020 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2d030 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2d040 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2d050 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2d060 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2d070 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2d080 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2d090 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2d0a0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2d0b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2d0c0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2d0d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2d0e0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2d0f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2d100 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2d110 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2d120 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2d130 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2d140 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2d150 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2d160 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2d170 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2d180 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2d190 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2d1a0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2d1b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2d1c0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2d1d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2d1e0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2d1f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2d200 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2d210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2d220 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2d230 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2d240 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2d250 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2d260 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2d270 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2d280 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2d290 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2d2a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2d2b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2d2c0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2d2d0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2d2e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2d2f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2d300 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2d310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2d320 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2d330 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2d340 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2d350 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2d360 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2d370 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2d380 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2d390 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2d3a0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2d3b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2d3c0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2d3d0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2d3e0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2d3f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2d400 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2d410 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2d420 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2d430 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2d440 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2d450 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2d460 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2d470 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2d480 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
2d490 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2d4a0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2d4b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2d4c0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2d4d0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2d4e0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2d4f0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 * ^The object re
2d500 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2d510 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2d520 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2d530 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2d540 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2d550 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
2d560 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2d570 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
2d580 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
2d590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2d5a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2d5b0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2d5c0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
2d5d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2d5e0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2d5f0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2d600 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2d610 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
2d620 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
2d630 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
2d640 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
2d650 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
2d660 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
2d670 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2d680 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
2d690 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2d6a0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
2d6b0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2d6c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
2d6d0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
2d6e0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2d6f0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
2d700 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a opriate. ^For.*
2d710 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2d720 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2d730 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2d740 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2d750 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2d760 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2d770 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2d780 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2d790 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2d7a0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2d7b0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 atically. ^(The
2d7c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
2d7d0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
2d7e0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
2d7f0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
2d800 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2d810 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2d820 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2d830 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
2d840 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
2d850 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
2d860 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
2d870 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2d880 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2d890 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2d8a0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
2d8b0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
2d8c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
2d8d0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
2d8e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2d8f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2d900 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 td> Result is a
2d910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2d920 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2d930 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2d940 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2d950 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2d960 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2d970 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
2d980 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2d990 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
2d9a0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2d9b0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2d9c0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
2d9d0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
2d9e0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
2d9f0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2da00 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
2da10 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
2da20 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
2da30 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2da40 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2da50 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
2da60 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
2da70 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2da80 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2da90 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
2daa0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a of the float.**
2dab0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2dac0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2dad0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
2dae0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 BLOB.** <tr><td
2daf0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
2db00 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
2db10 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
2db20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
2db30 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 XT <td> FLOA
2db40 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d T <td> [CAST]
2db50 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e to REAL.** <tr>
2db60 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2db70 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2db80 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
2db90 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2dba0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2dbb0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
2dbc0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
2dbd0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
2dbe0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2dbf0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a [CAST] to REAL.*
2dc00 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2dc10 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
2dc20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
2dc30 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
2dc40 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
2dc50 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
2dc60 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ote>)^.**.** The
2dc70 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
2dc80 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
2dc90 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
2dca0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
2dcb0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
2dcc0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
2dcd0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
2dce0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2dcf0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
2dd00 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
2dd10 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
2dd20 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
2dd30 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
2dd40 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
2dd50 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
2dd60 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
2dd70 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
2dd80 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
2dd90 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
2dda0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
2ddb0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
2ddc0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
2ddd0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
2dde0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
2ddf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2de00 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
2de10 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
2de20 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
2de30 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
2de40 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
2de50 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
2de60 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
2de70 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
2de80 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
2de90 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
2dea0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
2deb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
2dec0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2ded0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
2dee0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2def0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2df00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2df10 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2df20 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
2df30 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
2df40 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
2df50 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
2df60 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
2df70 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
2df80 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
2df90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2dfa0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
2dfb0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2dfc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2dfd0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
2dfe0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
2dff0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
2e000 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
2e010 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
2e020 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2e030 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
2e040 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2e050 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
2e060 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
2e070 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
2e080 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2e090 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2e0a0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2e0b0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
2e0c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 ul>.**.** ^Conve
2e0d0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 rsions between U
2e0e0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d TF-16be and UTF-
2e0f0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 16le are always
2e100 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e done in place an
2e110 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 d do.** not inva
2e120 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 lidate a prior p
2e130 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f ointer, though o
2e140 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e f course the con
2e150 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 tent of the buff
2e160 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 er.** that the p
2e170 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 rior pointer ref
2e180 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 erences will hav
2e190 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
2e1a0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
2e1b0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
2e1c0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
2e1d0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
2e1e0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
2e1f0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
2e200 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
2e210 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
2e220 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
2e230 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
2e240 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
2e250 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
2e260 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
2e270 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
2e280 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
2e290 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
2e2a0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
2e2b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
2e2c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2e2d0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
2e2e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
2e2f0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
2e300 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
2e310 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
2e320 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
2e330 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
2e340 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
2e350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2e360 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
2e370 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2e380 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
2e390 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
2e3a0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
2e3b0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
2e3c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2e3d0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
2e3e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
2e3f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2e400 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
2e410 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
2e420 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
2e430 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
2e440 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
2e450 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2e460 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
2e470 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2e480 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
2e490 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
2e4a0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
2e4b0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
2e4c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
2e4d0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2e4e0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
2e4f0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
2e500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2e510 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
2e520 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
2e530 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2e540 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
2e550 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2e560 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
2e570 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
2e580 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
2e590 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
2e5a0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
2e5b0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
2e5c0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
2e5d0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
2e5e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
2e5f0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2e600 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2e610 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
2e620 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
2e630 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
2e640 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
2e650 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
2e660 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
2e670 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
2e680 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
2e690 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 rned.** from [sq
2e6a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2e6b0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
2e6c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
2e6d0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
2e6e0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
2e6f0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
2e700 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2e710 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2e720 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
2e730 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
2e740 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
2e750 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
2e760 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
2e770 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
2e780 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
2e790 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
2e7a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2e7b0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
2e7c0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
2e7d0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
2e7e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
2e7f0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
2e800 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
2e810 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 MEM].)^.*/.const
2e820 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2e830 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
2e840 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2e850 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
2e860 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
2e870 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2e880 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
2e890 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2e8a0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2e8b0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 , int iCol);.dou
2e8c0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
2e8d0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
2e8e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2e8f0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2e900 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
2e910 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2e920 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ol);.sqlite3_int
2e930 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
2e940 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
2e950 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2e960 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
2e970 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2e980 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
2e990 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2e9a0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ol);.const void
2e9b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2e9c0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2e9d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2e9e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2e9f0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
2ea00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2ea10 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 );.sqlite3_value
2ea20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2ea30 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
2ea40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2ea50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ea60 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
2ea70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2ea80 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bject.**.** ^The
2ea90 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
2eaa0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
2eab0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
2eac0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2ead0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 tement]..** ^If
2eae0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2eaf0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 evaluation of th
2eb00 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f e statement enco
2eb10 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 untered no error
2eb20 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 s.** or if the s
2eb30 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 tatement is neve
2eb40 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 r been evaluated
2eb50 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 , then sqlite3_f
2eb60 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e inalize() return
2eb70 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 s.** SQLITE_OK.
2eb80 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
2eb90 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
2eba0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 of statement S f
2ebb0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 ailed, then.** s
2ebc0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2ebd0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 S) returns the a
2ebe0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
2ebf0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 r code] or.** [e
2ec00 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
2ec10 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
2ec20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2ec30 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 (S) routine can
2ec40 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
2ec50 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a point during.**
2ec60 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 the life cycle
2ec70 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
2ec80 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 tement] S:.** be
2ec90 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 fore statement S
2eca0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 is ever evaluat
2ecb0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 ed, after.** one
2ecc0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 or more calls t
2ecd0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
2ece0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e ()], or after an
2ecf0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 y call.** to [sq
2ed00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
2ed10 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
2ed20 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 her or not the s
2ed30 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 tatement has.**
2ed40 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 completed execut
2ed50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f ion..**.** ^Invo
2ed60 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e king sqlite3_fin
2ed70 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c alize() on a NUL
2ed80 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
2ed90 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
2eda0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
2edb0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 tion must finali
2edc0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 ze every [prepar
2edd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
2ede0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a order to avoid.
2edf0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b ** resource leak
2ee00 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 s. It is a grie
2ee10 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 vous error for t
2ee20 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
2ee30 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 o try to use.**
2ee40 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2ee50 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
2ee60 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
2ee70 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 . Any use of a
2ee80 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
2ee90 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
2eea0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
2eeb0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 d can result in
2eec0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a undefined and.**
2eed0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
2eee0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 avior such as se
2eef0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 gfaults and heap
2ef00 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
2ef10 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
2ef20 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
2ef30 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2ef40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2ef50 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
2ef60 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
2ef70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
2ef80 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
2ef90 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
2efa0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
2efb0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
2efc0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
2efd0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
2efe0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
2eff0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
2f000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
2f010 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
2f020 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
2f030 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
2f040 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
2f050 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
2f060 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
2f070 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
2f080 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
2f090 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2f0a0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
2f0b0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
2f0c0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
2f0d0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
2f0e0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
2f0f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2f100 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
2f110 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
2f120 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
2f130 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
2f140 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
2f150 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
2f160 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
2f170 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2f180 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
2f190 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
2f1a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
2f1b0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
2f1c0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
2f1d0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
2f1e0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
2f1f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
2f200 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
2f210 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
2f220 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
2f230 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
2f240 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
2f250 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
2f260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2f270 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
2f280 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
2f290 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
2f2a0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
2f2b0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
2f2c0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
2f2d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2f2e0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
2f2f0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
2f300 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
2f310 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
2f320 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
2f330 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
2f340 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
2f350 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
2f360 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
2f370 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2f380 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
2f390 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
2f3a0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
2f3b0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
2f3c0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
2f3d0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
2f3e0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2f3f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2f400 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
2f410 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
2f420 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2f430 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions}.**.** ^Th
2f440 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
2f450 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
2f460 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
2f470 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
2f480 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
2f490 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
2f4a0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2f4b0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
2f4c0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
2f4d0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
2f4e0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
2f4f0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
2f500 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
2f510 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
2f520 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
2f530 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
2f540 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
2f550 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
2f560 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
2f570 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
2f580 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
2f590 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
2f5a0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
2f5b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
2f5c0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
2f5d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
2f5e0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
2f5f0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
2f600 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
2f610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f620 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
2f630 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
2f640 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
2f650 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
2f660 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
2f670 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
2f680 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
2f690 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
2f6a0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
2f6b0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
2f6c0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
2f6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f6e0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
2f6f0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
2f700 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2f710 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
2f720 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
2f730 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
2f740 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
2f750 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
2f760 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
2f770 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
2f780 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
2f790 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
2f7a0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
2f7b0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
2f7c0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
2f7d0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
2f7e0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
2f7f0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
2f800 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
2f810 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
2f820 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
2f830 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
2f840 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
2f850 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
2f860 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
2f870 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
2f880 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
2f890 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
2f8a0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
2f8b0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
2f8c0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
2f8d0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
2f8e0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
2f8f0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
2f900 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
2f910 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
2f920 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
2f930 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
2f940 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
2f950 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
2f960 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
2f970 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
2f980 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
2f990 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
2f9a0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
2f9b0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
2f9c0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
2f9d0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
2f9e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
2f9f0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
2fa00 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
2fa10 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
2fa20 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
2fa30 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
2fa40 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
2fa50 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
2fa60 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
2fa70 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
2fa80 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 eters. Every SQ
2fa90 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 L function imple
2faa0 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 mentation must b
2fab0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a e able to work.*
2fac0 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 * with UTF-8, UT
2fad0 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 F-16le, or UTF-1
2fae0 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6be. But some i
2faf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
2fb00 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 ay be.** more ef
2fb10 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 ficient with one
2fb20 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 encoding than a
2fb30 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 nother. ^An app
2fb40 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 lication may.**
2fb50 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 invoke sqlite3_c
2fb60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
2fb70 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 or sqlite3_crea
2fb80 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 te_function16()
2fb90 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 multiple.** time
2fba0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 s with the same
2fbb0 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 function but wit
2fbc0 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 h different valu
2fbd0 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a es of eTextRep..
2fbe0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c ** ^When multipl
2fbf0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2fc00 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 s of the same fu
2fc10 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c nction are avail
2fc20 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 able, SQLite.**
2fc30 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e will pick the on
2fc40 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 e that involves
2fc50 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
2fc60 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 of data convers
2fc70 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 ion..** If there
2fc80 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c is only a singl
2fc90 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
2fca0 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 which does not
2fcb0 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a care what text.*
2fcc0 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 * encoding is us
2fcd0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 ed, then the fou
2fce0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rth argument sho
2fcf0 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 uld be [SQLITE_A
2fd00 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 NY]..**.** ^(The
2fd10 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 fifth parameter
2fd20 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 is an arbitrary
2fd30 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 pointer. The i
2fd40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2fd50 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e the.** function
2fd60 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 can gain access
2fd70 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 to this pointer
2fd80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2fd90 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a user_data()].)^.
2fda0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 **.** ^The sixth
2fdb0 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 , seventh and ei
2fdc0 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c ghth parameters,
2fdd0 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e xFunc, xStep an
2fde0 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a d xFinal, are.**
2fdf0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c pointers to C-l
2fe00 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e anguage function
2fe10 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
2fe20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
2fe30 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 n or.** aggregat
2fe40 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c e. ^A scalar SQL
2fe50 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 function requir
2fe60 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 es an implementa
2fe70 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e tion of the xFun
2fe80 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e c.** callback on
2fe90 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ly; NULL pointer
2fea0 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 s must be passed
2feb0 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e as the xStep an
2fec0 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 d xFinal.** para
2fed0 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 meters. ^An aggr
2fee0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 egate SQL functi
2fef0 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
2ff00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
2ff10 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 xStep.** and xF
2ff20 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f inal and NULL po
2ff30 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 inter must be pa
2ff40 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 ssed for xFunc.
2ff50 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 ^To delete an ex
2ff60 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 isting.** SQL fu
2ff70 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 nction or aggreg
2ff80 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 ate, pass NULL p
2ff90 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 ointers for all
2ffa0 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a three function.*
2ffb0 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a * callbacks..**.
2ffc0 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 ** ^(If the nint
2ffd0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2ffe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2fff0 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e nction_v2() is n
30000 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e ot NULL,.** then
30010 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f it is destructo
30020 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
30030 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
30040 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 er. .** The dest
30050 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 ructor is invoke
30060 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 d when the funct
30070 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 ion is deleted,
30080 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a either by being.
30090 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 ** overloaded or
300a0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
300b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c se connection cl
300c0 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 oses.)^.** ^The
300d0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c destructor is al
300e0 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 so invoked if th
300f0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c e call to.** sql
30100 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
30110 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e tion_v2() fails.
30120 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 .** ^When the de
30130 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
30140 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 k of the tenth p
30150 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f arameter is invo
30160 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 ked, it.** is pa
30170 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 ssed a single ar
30180 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
30190 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 a copy of the ap
301a0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a plication data .
301b0 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 ** pointer which
301c0 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 was the fifth p
301d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
301e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
301f0 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 ion_v2()..**.**
30200 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 ^It is permitted
30210 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c to register mul
30220 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
30230 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
30240 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 e.** functions w
30250 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ith the same nam
30260 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 e but with eithe
30270 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 r differing numb
30280 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 ers of.** argume
30290 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 nts or differing
302a0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 preferred text
302b0 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c encodings. ^SQL
302c0 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 ite will use.**
302d0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
302e0 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f on that most clo
302f0 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 sely matches the
30300 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 way in which th
30310 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f e.** SQL functio
30320 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 n is used. ^A f
30330 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
30340 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f tation with a no
30350 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 n-negative.** nA
30360 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rg parameter is
30370 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 a better match t
30380 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 han a function i
30390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
303a0 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 th.** a negative
303b0 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 nArg. ^A funct
303c0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 ion where the pr
303d0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
303e0 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 oding.** matches
303f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e the database en
30400 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 coding is a bett
30410 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e er.** match than
30420 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 a function wher
30430 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 e the encoding i
30440 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a s different. .*
30450 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 * ^A function wh
30460 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
30470 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 difference is b
30480 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 etween UTF16le a
30490 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 nd UTF16be.** is
304a0 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 a closer match
304b0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
304c0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
304d0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
304e0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 .** between UTF8
304f0 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a and UTF16..**.*
30500 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 * ^Built-in func
30510 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 tions may be ove
30520 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 rloaded by new a
30530 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
30540 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a ed functions..**
30550 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 .** ^An applicat
30560 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
30570 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 tion is permitte
30580 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a d to call other.
30590 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ** SQLite interf
305a0 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 aces. However,
305b0 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 such calls must
305c0 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 not.** close the
305d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
305e0 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a tion nor finaliz
305f0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 e or reset the p
30600 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
30610 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 ment in which th
30620 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 e function is ru
30630 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 nning..*/.int sq
30640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30650 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 ction(. sqlite3
30660 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 *db,. const ch
30670 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d ar *zFunctionNam
30680 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 e,. int nArg,.
30690 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 int eTextRep,.
306a0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 void *pApp,. v
306b0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c oid (*xFunc)(sql
306c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
306d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
306e0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 *),. void (*xSt
306f0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ep)(sqlite3_cont
30700 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 ext*,int,sqlite3
30710 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 _value**),. voi
30720 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 d (*xFinal)(sqli
30730 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b te3_context*).);
30740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 .int sqlite3_cre
30750 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
30760 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
30770 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
30780 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
30790 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
307a0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
307b0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
307c0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
307d0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
307e0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
307f0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
30800 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
30810 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
30820 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
30830 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
30840 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 text*).);.int sq
30850 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
30860 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ction_v2(. sqli
30870 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
30880 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
30890 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
308a0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
308b0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
308c0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
308d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
308e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
308f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
30900 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
30910 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
30920 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
30930 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
30940 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
30950 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
30960 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f oy)(void*).);../
30970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
30980 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a ext Encodings.**
30990 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
309a0 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
309b0 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
309c0 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
309d0 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
309e0 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
309f0 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
30a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
30a10 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 1.#de
30a20 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
30a30 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 6LE 2.#de
30a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
30a50 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 6BE 3.#de
30a60 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
30a70 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 6 4
30a80 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 /* Use native by
30a90 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 te order */.#def
30aa0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 ine SQLITE_ANY
30ab0 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 5 /
30ac0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
30ad0 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a _function only *
30ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
30af0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 _UTF16_ALIGNED
30b00 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 8 /* sqlite3_
30b10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
30b20 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 only */../*.**
30b30 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 CAPI3REF: Deprec
30b40 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ated Functions.*
30b50 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a * DEPRECATED.**.
30b60 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
30b70 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 ns are [deprecat
30b80 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 ed]. In order t
30b90 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 o maintain.** ba
30ba0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
30bb0 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 ility with older
30bc0 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e code, these fun
30bd0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 ctions continue
30be0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 .** to be suppor
30bf0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e ted. However, n
30c00 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
30c10 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 should avoid.**
30c20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 the use of these
30c30 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 functions. To
30c40 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 help encourage p
30c50 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a eople to avoid.*
30c60 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 * using these fu
30c70 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 nctions, we are
30c80 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c not going to tel
30c90 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 l you what they
30ca0 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 do..*/.#ifndef S
30cb0 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 QLITE_OMIT_DEPRE
30cc0 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 CATED.SQLITE_DEP
30cd0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
30ce0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
30cf0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
30d00 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 ext*);.SQLITE_DE
30d10 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
30d20 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c ite3_expired(sql
30d30 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c ite3_stmt*);.SQL
30d40 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
30d50 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 nt sqlite3_trans
30d60 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c fer_bindings(sql
30d70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 ite3_stmt*, sqli
30d80 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
30d90 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
30da0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c t sqlite3_global
30db0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a _recover(void);.
30dc0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
30dd0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 D void sqlite3_t
30de0 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f hread_cleanup(vo
30df0 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 id);.SQLITE_DEPR
30e00 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 ECATED int sqlit
30e10 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
30e20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
30e30 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
30e40 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
30e50 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 void*,sq
30e60 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
30e70 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
30e80 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
30e90 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 SQL Function Par
30ea0 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a ameter Values.**
30eb0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 .** The C-langua
30ec0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ge implementatio
30ed0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f n of SQL functio
30ee0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
30ef0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 s uses.** this s
30f00 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 et of interface
30f10 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 routines to acce
30f20 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ss the parameter
30f30 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 values on.** th
30f40 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 e function or ag
30f50 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 gregate..**.** T
30f60 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 he xFunc (for sc
30f70 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 alar functions)
30f80 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 or xStep (for ag
30f90 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 gregates) parame
30fa0 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ters.** to [sqli
30fb0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
30fc0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
30fd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
30fe0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 ion16()].** defi
30ff0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 ne callbacks tha
31000 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
31010 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
31020 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a d aggregates..**
31030 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 The 3rd paramet
31040 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c er to these call
31050 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 backs is an arra
31060 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
31070 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 .** [protected s
31080 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
31090 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 jects. There is
310a0 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 one [sqlite3_va
310b0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a lue] object for.
310c0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 ** each paramete
310d0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e r to the SQL fun
310e0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f ction. These ro
310f0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
31100 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 to.** extract va
31110 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 lues from the [s
31120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
31130 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 jects..**.** The
31140 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
31150 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 only with [prot
31160 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
31170 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
31180 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
31190 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e use these routin
311a0 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 es on an [unprot
311b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
311c0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 lue].** object r
311d0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
311e0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
311f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
31200 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
31210 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
31220 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 ding [column acc
31230 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a ess functions].*
31240 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 * except that t
31250 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
31260 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f ke a single [pro
31270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
31280 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
31290 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 pointer instead
312a0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 of a [sqlite3_st
312b0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 mt*] pointer and
312c0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 an integer colu
312d0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a mn number..**.**
312e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
312f0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
31300 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
31310 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a a UTF-16 string.
31320 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ** in the native
31330 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 byte-order of t
31340 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e he host machine.
31350 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
31360 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
31370 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
31380 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 alue_text16le()
31390 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 interfaces.** ex
313a0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 tract UTF-16 str
313b0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 ings as big-endi
313c0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e an and little-en
313d0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c dian respectivel
313e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 y..**.** ^(The s
313f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
31400 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
31410 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
31420 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
31430 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
31440 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
31450 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
31460 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
31470 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
31480 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
31490 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
314a0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
314b0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
314c0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
314d0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
314e0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 rmation (in othe
314f0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 r.** words, if t
31500 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 he value is a st
31510 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 ring that looks
31520 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a like a number).*
31530 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 * then the conve
31540 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
31550 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e ed. Otherwise n
31560 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 o conversion occ
31570 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c urs..** The [SQL
31580 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
31590 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
315a0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
315b0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c rned.)^.**.** Pl
315c0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 ease pay particu
315d0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f lar attention to
315e0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 the fact that t
315f0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 he pointer retur
31600 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
31610 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
31620 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
31630 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a ue_text()], or.*
31640 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
31650 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 _text16()] can b
31660 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 e invalidated by
31670 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 a subsequent ca
31680 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
31690 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
316a0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
316b0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 _bytes16()], [sq
316c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
316d0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
316e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
316f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
31700 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
31710 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
31720 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 e same thread as
31730 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
31740 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 tion that suppli
31750 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ed the [sqlite3_
31760 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 value*] paramete
31770 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 rs..*/.const voi
31780 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
31790 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 _blob(sqlite3_va
317a0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
317b0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 e3_value_bytes(s
317c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
317d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
317e0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 e_bytes16(sqlite
317f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 3_value*);.doubl
31800 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
31810 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 double(sqlite3_v
31820 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 alue*);.int sqli
31830 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 te3_value_int(sq
31840 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 lite3_value*);.s
31850 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
31860 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 ite3_value_int64
31870 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
31880 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
31890 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
318a0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
318b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
318c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
318d0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 alue_text16(sqli
318e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e te3_value*);.con
318f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
31900 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 _value_text16le(
31910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
31920 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
31930 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
31940 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6be(sqlite3_valu
31950 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
31960 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 _value_type(sqli
31970 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 te3_value*);.int
31980 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e sqlite3_value_n
31990 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 umeric_type(sqli
319a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a te3_value*);../*
319b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
319c0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 tain Aggregate F
319d0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a unction Context.
319e0 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 **.** Implementa
319f0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 tions of aggrega
31a00 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 te SQL functions
31a10 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 use this.** rou
31a20 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 tine to allocate
31a30 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 memory for stor
31a40 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e ing their state.
31a50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
31a60 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 t time the sqlit
31a70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
31a80 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e text(C,N) routin
31a90 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 e is called .**
31aa0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
31ab0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 aggregate funct
31ac0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 ion, SQLite.** a
31ad0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 llocates N of me
31ae0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 mory, zeroes out
31af0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e that memory, an
31b00 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e d returns a poin
31b10 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 ter.** to the ne
31b20 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 w memory. ^On se
31b30 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 cond and subsequ
31b40 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 ent calls to.**
31b50 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
31b60 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 e_context() for
31b70 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
31b80 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
31b90 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d ance,.** the sam
31ba0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 e buffer is retu
31bb0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 rned. Sqlite3_a
31bc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
31bd0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a () is normally.*
31be0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f * called once fo
31bf0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f r each invocatio
31c00 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 n of the xStep c
31c10 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e allback and then
31c20 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d one.** last tim
31c30 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 e when the xFina
31c40 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e l callback is in
31c50 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e voked. ^(When n
31c60 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 o rows match.**
31c70 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 an aggregate que
31c80 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 ry, the xStep()
31c90 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 callback of the
31ca0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
31cb0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 on.** implementa
31cc0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 tion is never ca
31cd0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 lled and xFinal(
31ce0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 ) is called exac
31cf0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 tly once..** In
31d00 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c those cases, sql
31d10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
31d20 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 ontext() might b
31d30 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 e called for the
31d40 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 .** first time f
31d50 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 rom within xFina
31d60 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 l().)^.**.** ^Th
31d70 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
31d80 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
31d90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
31da0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
31db0 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 .** when first c
31dc0 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 alled if N is le
31dd0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
31de0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 to zero or if a
31df0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
31e00 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 ate error occurs
31e10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d ..**.** ^(The am
31e20 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c ount of space al
31e30 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
31e40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
31e50 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 text(C,N) is.**
31e60 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 determined by th
31e70 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e e N parameter on
31e80 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 first successfu
31e90 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e l call. Changin
31ea0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f g the.** value o
31eb0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e f N in subsequen
31ec0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 t call to sqlite
31ed0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
31ee0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 ext() within.**
31ef0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 the same aggrega
31f00 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 te function inst
31f10 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 ance will not re
31f20 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a size the memory.
31f30 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e ** allocation.)^
31f40 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 Within the xFi
31f50 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 nal callback, it
31f60 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f is customary to
31f70 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 set.** N=0 in c
31f80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
31f90 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
31fa0 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e t(C,N) so that n
31fb0 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 o .** pointless
31fc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
31fd0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 ns occur..**.**
31fe0 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 ^SQLite automati
31ff0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 cally frees the
32000 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 memory allocated
32010 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f by .** sqlite3_
32020 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
32030 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 t() when the agg
32040 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e regate query con
32050 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 cludes..**.** Th
32060 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
32070 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 r must be a copy
32080 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
32090 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 te3_context | SQ
320a0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 L function conte
320b0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 xt] that is the
320c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a first parameter.
320d0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 ** to the xStep
320e0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 or xFinal callba
320f0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 ck routine that
32100 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 implements the a
32110 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 ggregate.** func
32120 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 tion..**.** This
32130 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 routine must be
32140 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
32150 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
32160 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 which.** the agg
32170 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
32180 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
32190 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
321a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
321b0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
321c0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 xt*, int nBytes)
321d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
321e0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 F: User Data For
321f0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
32200 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 ^The sqlite3_us
32210 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 er_data() interf
32220 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
32230 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
32240 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 nter that was th
32250 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 e pUserData para
32260 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 meter (the 5th p
32270 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
32280 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
32290 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
322a0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
322b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
322c0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
322d0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
322e0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
322f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
32300 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
32310 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
32320 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
32330 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
32340 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
32350 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
32360 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
32370 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
32380 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 .void *sqlite3_u
32390 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 ser_data(sqlite3
323a0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a _context*);../*.
323b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
323c0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
323d0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
323e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
323f0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
32400 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 dle() interface
32410 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f returns a copy o
32420 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 f.** the pointer
32430 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 to the [databas
32440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 e connection] (t
32450 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 he 1st parameter
32460 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c ).** of the [sql
32470 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
32480 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b tion()].** and [
32490 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
324a0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 unction16()] rou
324b0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 tines that origi
324c0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 nally.** registe
324d0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 red the applicat
324e0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 ion defined func
324f0 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 tion..*/.sqlite3
32500 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 *sqlite3_contex
32510 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 t_db_handle(sqli
32520 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
32530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32540 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 Function Auxilia
32550 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 ry Data.**.** Th
32560 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 ese functions ma
32570 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f y be used by (no
32580 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c n-aggregate) SQL
32590 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a functions to.**
325a0 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 associate metad
325b0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e ata with argumen
325c0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 t values. If the
325d0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 same value is p
325e0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 assed to.** mult
325f0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 iple invocations
32600 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c of the same SQL
32610 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 function during
32620 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e query execution
32630 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 , under.** some
32640 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 circumstances th
32650 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 e associated met
32660 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 adata may be pre
32670 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d served. An exam
32680 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 ple.** of where
32690 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 this might be us
326a0 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 eful is in a reg
326b0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 ular-expression
326c0 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 matching.** func
326d0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c tion. The compil
326e0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ed version of th
326f0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 e regular expres
32700 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 sion can be stor
32710 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 ed as.** metadat
32720 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 a associated wit
32730 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 h the pattern st
32740 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 ring. .** Then
32750 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 as long as the p
32760 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 attern string re
32770 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a mains the same,.
32780 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 ** the compiled
32790 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
327a0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 on can be reused
327b0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 on multiple.**
327c0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
327d0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e he same function
327e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
327f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
32800 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
32810 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
32820 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a o the metadata.*
32830 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 * associated by
32840 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
32850 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 auxdata() functi
32860 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 on with the Nth
32870 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 argument.** valu
32880 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 e to the applica
32890 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
328a0 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 ction. ^If there
328b0 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a is no metadata.
328c0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ** associated wi
328d0 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 th the function
328e0 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 argument, this s
328f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
32900 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a ta() interface.*
32910 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c * returns a NULL
32920 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
32930 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 ^The sqlite3_set
32940 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
32950 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 ) interface save
32960 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 s P as metadata
32970 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 for the N-th.**
32980 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 argument of the
32990 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
329a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e ned function. ^
329b0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 Subsequent.** ca
329c0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 lls to sqlite3_g
329d0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 et_auxdata(C,N)
329e0 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 return P from th
329f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a e most recent.**
32a00 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
32a10 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 data(C,N,P,X) ca
32a20 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 ll if the metada
32a30 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 ta is still vali
32a40 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 d or.** NULL if
32a50 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 the metadata has
32a60 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e been discarded.
32a70 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 .** ^After each
32a80 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
32a90 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
32aa0 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 P,X) where X is
32ab0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c not NULL,.** SQL
32ac0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 ite will invoke
32ad0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 the destructor f
32ae0 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 unction X with p
32af0 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 arameter P exact
32b00 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e ly.** once, when
32b10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 the metadata is
32b20 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 discarded..** S
32b30 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f QLite is free to
32b40 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 discard the met
32b50 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d adata at any tim
32b60 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 e, including: <u
32b70 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 l>.** <li> when
32b80 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
32b90 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d g function param
32ba0 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 eter changes, or
32bb0 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 .** <li> when [s
32bc0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
32bd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
32be0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 lize()] is calle
32bf0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 d for the.**
32c00 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c SQL statement,
32c10 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e or.** <li> when
32c20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
32c30 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 data() is invoke
32c40 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 d again on the s
32c50 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f ame parameter, o
32c60 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 r.** <li> during
32c70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 the original sq
32c80 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
32c90 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 a() call when a
32ca0 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 memory .**
32cb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
32cc0 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e occurs. </ul>)^
32cd0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 .**.** Note the
32ce0 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 last bullet in p
32cf0 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 articular. The
32d00 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 destructor X in
32d10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
32d20 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 auxdata(C,N,P,X)
32d30 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 might be called
32d40 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
32d50 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 fore the.** sqli
32d60 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
32d70 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e ) interface even
32d80 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 returns. Hence
32d90 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
32da0 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 data().** should
32db0 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 be called near
32dc0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 the end of the f
32dd0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
32de0 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a tation and the.*
32df0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 * function imple
32e00 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
32e10 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 not make any us
32e20 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 e of P after.**
32e30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
32e40 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 ata() has been c
32e50 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 alled..**.** ^(I
32e60 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 n practice, meta
32e70 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 data is preserve
32e80 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 d between functi
32e90 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 on calls for.**
32ea0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 function paramet
32eb0 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d ers that are com
32ec0 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 pile-time consta
32ed0 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c nts, including l
32ee0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 iteral.** values
32ef0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 and [parameters
32f00 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e ] and expression
32f10 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 s composed from
32f20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a the same.)^.**.*
32f30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
32f40 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
32f50 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
32f60 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
32f70 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
32f80 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
32f90 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 .void *sqlite3_g
32fa0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 et_auxdata(sqlit
32fb0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
32fc0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 N);.void sqlite
32fd0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_set_auxdata(sq
32fe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32ff0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f int N, void*, vo
33000 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a id (*)(void*));.
33010 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33020 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 : Constants Defi
33030 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 ning Special Des
33040 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 tructor Behavior
33050 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
33060 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 special values
33070 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 for the destruct
33080 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 or that is passe
33090 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
330a0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f inal argument to
330b0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
330c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
330d0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 lob()]. ^If the
330e0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
330f0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
33100 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
33110 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
33120 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
33130 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
33140 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
33150 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
33160 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
33170 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 yed. ^The.** SQ
33180 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 LITE_TRANSIENT v
33190 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 alue means that
331a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c the content will
331b0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 likely change i
331c0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 n.** the near fu
331d0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 ture and that SQ
331e0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 Lite should make
331f0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
33200 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
33210 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 content before r
33220 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
33230 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e The typedef is n
33240 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b ecessary to work
33250 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 around problems
33260 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 in certain.** C
33270 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f ++ compilers..*/
33280 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a .typedef void (*
33290 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
332a0 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b or_type)(void*);
332b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
332c0 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71 STATIC ((sq
332d0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
332e0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 _type)0).#define
332f0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e SQLITE_TRANSIEN
33300 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 T ((sqlite3_de
33310 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 structor_type)-1
33320 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 )../*.** CAPI3RE
33330 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 F: Setting The R
33340 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 esult Of An SQL
33350 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 Function.**.** T
33360 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
33370 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 e used by the xF
33380 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 unc or xFinal ca
33390 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 llbacks that.**
333a0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 implement SQL fu
333b0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
333c0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 egates. See.**
333d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
333e0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
333f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
33400 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
33410 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
33420 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
33430 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
33440 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 ns work very muc
33450 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 h like the [para
33460 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 meter binding] f
33470 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 amily of.** func
33480 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 tions used to bi
33490 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 nd values to hos
334a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 t parameters in
334b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
334c0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f nts..** Refer to
334d0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 the [SQL parame
334e0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ter] documentati
334f0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
33500 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
33510 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
33520 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 3_result_blob()
33530 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
33540 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
33550 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
33560 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
33570 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 n to be the BLOB
33580 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 whose content i
33590 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 s pointed.** to
335a0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 by the second pa
335b0 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 rameter and whic
335c0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e h is N bytes lon
335d0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 g where N is the
335e0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
335f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
33600 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
33610 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
33620 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
33630 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
33640 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
33650 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
33660 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
33670 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
33680 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
33690 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
336a0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
336b0 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
336c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
336d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
336e0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 ouble() interfac
336f0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
33700 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
33710 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
33720 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
33730 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
33740 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
33750 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 .** by its 2nd a
33760 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
33770 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33780 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
33790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
337a0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
337b0 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
337c0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
337d0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
337e0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
337f0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
33800 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 he string pointe
33810 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 d to by the.** 2
33820 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
33830 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33840 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 rror() or sqlite
33850 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
33860 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 ().** as the tex
33870 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 t of an error me
33880 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 ssage. ^SQLite
33890 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
338a0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
338b0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
338c0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
338d0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 () as UTF-8. ^SQ
338e0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 Lite.** interpre
338f0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 ts the string fr
33900 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
33910 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 t_error16() as U
33920 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a TF-16 in native.
33930 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 ** byte order.
33940 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
33950 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
33960 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
33970 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
33980 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
33990 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 is negative the
339a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 n SQLite takes a
339b0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
339c0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 essage all text
339d0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 up through the f
339e0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
339f0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
33a00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
33a10 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
33a20 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 t_error() or.**
33a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
33a40 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d rror16() is non-
33a50 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
33a60 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 Lite takes that
33a70 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e many.** bytes (n
33a80 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 ot characters) f
33a90 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
33aa0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 meter as the err
33ab0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e or message..** ^
33ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
33ad0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
33ae0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
33af0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 ror16().** routi
33b00 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 nes make a priva
33b10 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 te copy of the e
33b20 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
33b30 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 t before.** they
33b40 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c return. Hence,
33b50 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
33b60 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f ction can deallo
33b70 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 cate or.** modif
33b80 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 y the text after
33b90 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 they return wit
33ba0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 hout harm..** ^T
33bb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33bc0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 t_error_code() f
33bd0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 unction changes
33be0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a the error code.*
33bf0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 * returned by SQ
33c00 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 Lite as a result
33c10 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 of an error in
33c20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 a function. ^By
33c30 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 default,.** the
33c40 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 error code is S
33c50 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 QLITE_ERROR. ^A
33c60 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
33c70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
33c80 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
33c90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33ca0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 error16() resets
33cb0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
33cc0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e to SQLITE_ERROR.
33cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
33ce0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33cf0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
33d00 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
33d10 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
33d20 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
33d30 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
33d40 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c or BLOB is too l
33d50 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ong to represent
33d60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33d70 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
33d80 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 r_nomem() interf
33d90 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
33da0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
33db0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
33dc0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 g that a memory
33dd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 allocation faile
33de0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
33df0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
33e00 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
33e10 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
33e20 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
33e30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
33e40 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
33e50 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 the 32-bit signe
33e60 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
33e70 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
33e80 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
33e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
33ea0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 sult_int64() int
33eb0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
33ec0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
33ed0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
33ee0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33ef0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 ion to be the 64
33f00 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
33f10 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
33f20 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
33f30 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
33f40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33f50 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 t_null() interfa
33f60 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
33f70 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
33f80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
33f90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
33fa0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a to be NULL..**.*
33fb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
33fc0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 esult_text(), sq
33fd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
33fe0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 t16(),.** sqlite
33ff0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
34000 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 e(), and sqlite3
34010 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
34020 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
34030 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 set the return
34040 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 value of the app
34050 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34060 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a function to be.
34070 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 ** a text string
34080 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 which is repres
34090 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 ented as UTF-8,
340a0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
340b0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 te order,.** UTF
340c0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 -16 little endia
340d0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
340e0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 endian, respect
340f0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 ively..** ^SQLit
34100 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 e takes the text
34110 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 result from the
34120 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f application fro
34130 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 m.** the 2nd par
34140 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 ameter of the sq
34150 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
34160 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a t* interfaces..*
34170 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 * ^If the 3rd pa
34180 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
34190 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
341a0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a xt* interfaces.*
341b0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 * is negative, t
341c0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 hen SQLite takes
341d0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f result text fro
341e0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
341f0 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 ter.** through t
34200 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
34210 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 aracter..** ^If
34220 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
34230 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
34240 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
34250 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e terfaces.** is n
34260 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
34270 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 n as many bytes
34280 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 (not characters)
34290 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 of the text.**
342a0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 pointed to by th
342b0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
342c0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 are taken as the
342d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
342e0 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ined.** function
342f0 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 result. If the
34300 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 3rd parameter i
34310 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
34320 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 then it.** must
34330 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 be the byte offs
34340 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 et into the stri
34350 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c ng where the NUL
34360 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c terminator woul
34370 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 d.** appear if t
34380 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 he string where
34390 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 NUL terminated.
343a0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
343b0 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 acters occur.**
343c0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 in the string at
343d0 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 a byte offset t
343e0 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e hat is less than
343f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
34400 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 e 3rd.** paramet
34410 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 er, then the res
34420 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 ulting string wi
34430 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 ll contain embed
34440 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 ded NULs and the
34450 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 .** result of ex
34460 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 pressions operat
34470 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 ing on strings w
34480 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ith embedded NUL
34490 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a s is undefined..
344a0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 ** ^If the 4th p
344b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
344c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
344d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
344e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
344f0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e sult_blob is a n
34500 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c on-NULL pointer,
34510 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c then SQLite cal
34520 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 ls that.** funct
34530 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 ion as the destr
34540 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 uctor on the tex
34550 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 t or BLOB result
34560 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 when it has.**
34570 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
34580 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e hat result..** ^
34590 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
345a0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
345b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
345c0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 interfaces or t
345d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 o.** sqlite3_res
345e0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 ult_blob is the
345f0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 special constant
34600 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 SQLITE_STATIC,
34610 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 then SQLite.** a
34620 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 ssumes that the
34630 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
34640 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 ult is in consta
34650 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 nt space and doe
34660 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 s not.** copy th
34670 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
34680 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 parameter nor c
34690 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 all a destructor
346a0 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a on the content.
346b0 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 ** when it has f
346c0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 inished using th
346d0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 at result..** ^I
346e0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
346f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
34700 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
34710 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
34720 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34730 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 blob is the spec
34740 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c ial constant SQL
34750 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a ITE_TRANSIENT.**
34760 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b then SQLite mak
34770 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 es a copy of the
34780 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 result into spa
34790 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ce obtained from
347a0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
347b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 3_malloc()] befo
347c0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a re it returns..*
347d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
347e0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
347f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
34800 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a the result of.**
34810 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
34820 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
34830 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 n to be a copy t
34840 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 he.** [unprotect
34850 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
34860 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 ] object specifi
34870 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 ed by the 2nd pa
34880 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a rameter. ^The.*
34890 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 * sqlite3_result
348a0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 _value() interfa
348b0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 ce makes a copy
348c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
348d0 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 value].** so tha
348e0 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 t the [sqlite3_v
348f0 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 alue] specified
34900 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 in the parameter
34910 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a may change or.*
34920 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 * be deallocated
34930 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 after sqlite3_r
34940 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 esult_value() re
34950 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 turns without ha
34960 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 rm..** ^A [prote
34970 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
34980 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 ue] object may a
34990 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 lways be used wh
349a0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f ere an.** [unpro
349b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
349c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 alue] object is
349d0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 required, so eit
349e0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b her.** kind of [
349f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
34a00 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 bject can be use
34a10 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 d with this inte
34a20 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 rface..**.** If
34a30 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 these routines a
34a40 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 re called from w
34a50 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 ithin the differ
34a60 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 ent thread.** th
34a70 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 an the one conta
34a80 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 ining the applic
34a90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34aa0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 nction that rece
34ab0 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c ived.** the [sql
34ac0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f ite3_context] po
34ad0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c inter, the resul
34ae0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
34af0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
34b00 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 3_result_blob(sq
34b10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
34b20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
34b30 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 , void(*)(void*)
34b40 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
34b50 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 result_double(sq
34b60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
34b70 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 double);.void sq
34b80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
34b90 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 or(sqlite3_conte
34ba0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a xt*, const char*
34bb0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
34bc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
34bd0 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 r16(sqlite3_cont
34be0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
34bf0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 *, int);.void sq
34c00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
34c10 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 or_toobig(sqlite
34c20 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 3_context*);.voi
34c30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34c40 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
34c50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
34c60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
34c70 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
34c80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
34c90 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
34ca0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 te3_result_int(s
34cb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
34cc0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
34cd0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 te3_result_int64
34ce0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
34cf0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
34d00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
34d10 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 result_null(sqli
34d20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
34d30 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
34d40 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f lt_text(sqlite3_
34d50 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
34d60 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 char*, int, void
34d70 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
34d80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34d90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f _text16(sqlite3_
34da0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
34db0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 void*, int, void
34dc0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 (*)(void*));.voi
34dd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
34de0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
34df0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
34e00 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 t void*, int,voi
34e10 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
34e20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
34e30 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 t_text16be(sqlit
34e40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
34e50 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f st void*, int,vo
34e60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
34e70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
34e80 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 lt_value(sqlite3
34e90 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 _context*, sqlit
34ea0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 e3_value*);.void
34eb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34ec0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
34ed0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
34ee0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
34ef0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 EF: Define New C
34f00 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 ollating Sequenc
34f10 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 es.**.** ^These
34f20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 functions add, r
34f30 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 emove, or modify
34f40 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 a [collation] a
34f50 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
34f60 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
34f70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
34f80 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 ified as the fir
34f90 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a st argument..**.
34fa0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
34fb0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 the collation is
34fc0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a a UTF-8 string.
34fd0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 ** for sqlite3_c
34fe0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
34ff0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 ) and sqlite3_cr
35000 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
35010 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2().** and a UTF
35020 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 -16 string in na
35030 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 tive byte order
35040 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 for sqlite3_crea
35050 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
35060 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 ..** ^Collation
35070 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 names that compa
35080 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 re equal accordi
35090 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ng to [sqlite3_s
350a0 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a trnicmp()] are.*
350b0 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 * considered to
350c0 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 be the same name
350d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 ..**.** ^(The th
350e0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 ird argument (eT
350f0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 extRep) must be
35100 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 one of the const
35110 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ants:.** <ul>.**
35120 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 <li> [SQLITE_UT
35130 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 F8],.** <li> [SQ
35140 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a LITE_UTF16LE],.*
35150 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 * <li> [SQLITE_U
35160 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e TF16BE],.** <li>
35170 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c [SQLITE_UTF16],
35180 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c or.** <li> [SQL
35190 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
351a0 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a D]..** </ul>)^.*
351b0 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 * ^The eTextRep
351c0 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 argument determi
351d0 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 nes the encoding
351e0 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 of strings pass
351f0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c ed.** to the col
35200 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
35210 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 callback, xCallb
35220 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ack..** ^The [SQ
35230 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 LITE_UTF16] and
35240 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c [SQLITE_UTF16_AL
35250 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f IGNED] values fo
35260 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f r eTextRep.** fo
35270 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 rce strings to b
35280 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 e UTF16 with nat
35290 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
352a0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
352b0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 UTF16_ALIGNED] v
352c0 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 alue for eTextRe
352d0 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 p forces strings
352e0 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 to begin.** on
352f0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 an even byte add
35300 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ress..**.** ^The
35310 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
35320 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 , pArg, is an ap
35330 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
35340 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 ointer that is p
35350 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 assed.** through
35360 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 as the first ar
35370 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f gument to the co
35380 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
35390 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
353a0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 ^The fifth argu
353b0 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c ment, xCallback,
353c0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
353d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
353e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c unction..** ^Mul
353f0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 tiple collating
35400 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 functions can be
35410 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e registered usin
35420 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 g the same name
35430 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 but.** with diff
35440 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 erent eTextRep p
35450 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 arameters and SQ
35460 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 Lite will use wh
35470 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 ichever.** funct
35480 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 ion requires the
35490 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
354a0 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 data transforma
354b0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 tion..** ^If the
354c0 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d xCallback argum
354d0 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e ent is NULL then
354e0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 the collating f
354f0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 unction is.** de
35500 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c leted. ^When al
35510 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 l collating func
35520 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 tions having the
35530 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 same name are d
35540 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 eleted,.** that
35550 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 collation is no
35560 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a longer usable..*
35570 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 *.** ^The collat
35580 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c ing function cal
35590 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
355a0 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 with a copy of
355b0 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 the pArg .** app
355c0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
355d0 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 inter and with t
355e0 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 wo strings in th
355f0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 e encoding speci
35600 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 fied.** by the e
35610 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 TextRep argument
35620 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 . The collating
35630 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 function must r
35640 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 eturn an.** inte
35650 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 ger that is nega
35660 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 tive, zero, or p
35670 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 ositive.** if th
35680 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 e first string i
35690 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 s less than, equ
356a0 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 al to, or greate
356b0 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e r than the secon
356c0 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 d,.** respective
356d0 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 ly. A collating
356e0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 function must a
356f0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 lways return the
35700 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 same answer.**
35710 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 given the same i
35720 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f nputs. If two o
35730 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 r more collating
35740 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 functions are r
35750 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 egistered.** to
35760 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 the same collati
35770 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 on name (using d
35780 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 ifferent eTextRe
35790 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 p values) then a
357a0 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 ll.** must give
357b0 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e an equivalent an
357c0 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 swer when invoke
357d0 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e d with equivalen
357e0 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 t strings..** Th
357f0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
35800 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 tion must obey t
35810 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f he following pro
35820 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a perties for all.
35830 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c ** strings A, B,
35840 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f and C:.**.** <o
35850 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d l>.** <li> If A=
35860 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a =B then B==A..**
35870 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e <li> If A==B an
35880 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 d B==C then A==C
35890 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c ..** <li> If A&l
358a0 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e t;B THEN B>A.
358b0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 .** <li> If A<
358c0 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 ;B and B<C th
358d0 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f en A<C..** </
358e0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 ol>.**.** If a c
358f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
35900 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 n fails any of t
35910 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 he above constra
35920 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a ints and that.**
35930 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
35940 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 ion is register
35950 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 ed and used, the
35960 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f n the behavior o
35970 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 f SQLite.** is u
35980 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
35990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 ^The sqlite3_cre
359a0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
359b0 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 () works like sq
359c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
359d0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 lation().** with
359e0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 the addition th
359f0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 at the xDestroy
35a00 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
35a10 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e ked on pArg when
35a20 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e .** the collatin
35a30 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 g function is de
35a40 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 leted..** ^Colla
35a50 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 ting functions a
35a60 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 re deleted when
35a70 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 they are overrid
35a80 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 den by later.**
35a90 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c calls to the col
35aa0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 lation creation
35ab0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 functions or whe
35ac0 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 n the.** [databa
35ad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
35ae0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b s closed using [
35af0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
35b00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 ..**.** ^The xDe
35b10 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 stroy callback i
35b20 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c s <u>not</u> cal
35b30 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 led if the .** s
35b40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f qlite3_create_co
35b50 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e llation_v2() fun
35b60 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 ction fails. Ap
35b70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
35b80 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 invoke.** sqlite
35b90 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
35ba0 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e on_v2() with a n
35bb0 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 on-NULL xDestroy
35bc0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
35bd0 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 .** check the r
35be0 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 eturn code and d
35bf0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 ispose of the ap
35c00 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
35c10 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 ointer.** themse
35c20 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e lves rather than
35c30 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 expecting SQLit
35c40 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 e to deal with i
35c50 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 t for them..** T
35c60 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 his is different
35c70 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 from every othe
35c80 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
35c90 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 ce. The inconsi
35ca0 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e stency .** is un
35cb0 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 fortunate but ca
35cc0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 nnot be changed
35cd0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
35ce0 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 backwards .** c
35cf0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
35d00 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b .** See also: [
35d10 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
35d20 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 n_needed()] and
35d30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 [sqlite3_collati
35d40 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a on_needed16()]..
35d50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
35d60 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 reate_collation(
35d70 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
35d80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
35d90 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
35da0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 ep, . void *pAr
35db0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 g,. int(*xCompa
35dc0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
35dd0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
35de0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e nst void*).);.in
35df0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
35e00 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 _collation_v2(.
35e10 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
35e20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
35e30 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
35e40 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
35e50 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
35e60 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
35e70 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
35e80 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 t void*),. void
35e90 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 (*xDestroy)(void
35ea0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
35eb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
35ec0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a on16(. sqlite3*
35ed0 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 , . const void
35ee0 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 *zName,. int eT
35ef0 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 extRep, . void
35f00 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 *pArg,. int(*xC
35f10 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e ompare)(void*,in
35f20 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e t,const void*,in
35f30 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 t,const void*).)
35f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
35f50 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 F: Collation Nee
35f60 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ded Callbacks.**
35f70 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 .** ^To avoid ha
35f80 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 ving to register
35f90 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 all collation s
35fa0 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 equences before
35fb0 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 a database.** ca
35fc0 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e n be used, a sin
35fd0 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e gle callback fun
35fe0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
35ff0 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 istered with the
36000 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
36010 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 nnection] to be
36020 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
36030 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f an undefined co
36040 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 llation.** seque
36050 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e nce is required.
36060 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
36070 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 unction is regis
36080 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 tered using the
36090 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
360a0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a n_needed() API,.
360b0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 ** then it is pa
360c0 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f ssed the names o
360d0 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c f undefined coll
360e0 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 ation sequences
360f0 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e as strings.** en
36100 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 coded in UTF-8.
36110 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c ^If sqlite3_coll
36120 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
36130 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 is used,.** the
36140 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 names are passe
36150 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d d as UTF-16 in m
36160 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 achine native by
36170 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 te order..** ^A
36180 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 call to either f
36190 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 unction replaces
361a0 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f the existing co
361b0 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 llation-needed c
361c0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
361d0 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 (When the callba
361e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 ck is invoked, t
361f0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
36200 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f t passed is a co
36210 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 py.** of the sec
36220 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
36230 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
36240 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a n_needed() or.**
36250 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
36260 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 on_needed16().
36270 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
36280 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 ent is the datab
36290 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
362a0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 n. The third ar
362b0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 gument is one of
362c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
362d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
362e0 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f ,.** or [SQLITE_
362f0 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 UTF16LE], indica
36300 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 ting the most de
36310 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 sirable form of
36320 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a the collation.**
36330 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 sequence functi
36340 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 on required. Th
36350 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
36360 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
36370 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 f the.** require
36380 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 d collation sequ
36390 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 ence.)^.**.** Th
363a0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
363b0 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 ion should regis
363c0 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 ter the desired
363d0 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a collation using.
363e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
363f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c te_collation()],
36400 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
36410 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c _collation16()],
36420 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
36430 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
36440 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 _v2()]..*/.int s
36450 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
36460 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 _needed(. sqlit
36470 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a e3*, . void*, .
36480 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c void(*)(void*,
36490 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 sqlite3*,int eTe
364a0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 xtRep,const char
364b0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 *).);.int sqlite
364c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 3_collation_need
364d0 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a ed16(. sqlite3*
364e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f , . void*,. vo
364f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 id(*)(void*,sqli
36500 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 te3*,int eTextRe
36510 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 p,const void*).)
36520 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 ;..#ifdef SQLITE
36530 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a _HAS_CODEC./*.**
36540 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 Specify the key
36550 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 for an encrypte
36560 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 d database. Thi
36570 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 s routine should
36580 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 be.** called ri
36590 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 ght after sqlite
365a0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_open()..**.**
365b0 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
365c0 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
365d0 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
365e0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
365f0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
36600 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 te..*/.int sqlit
36610 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 e3_key(. sqlite
36620 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
36630 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
36640 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
36650 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
36660 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
36670 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
36680 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 y */.);.int sqli
36690 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 73 71 te3_key_v2(. sq
366a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
366b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
366c0 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 Database to be r
366d0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 ekeyed */. cons
366e0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c t char *zDbName,
366f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 /* Na
36700 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 me of the databa
36710 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f se */. const vo
36720 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
36730 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
36740 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 y */.);../*.** C
36750 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e hange the key on
36760 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 an open databas
36770 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 e. If the curre
36780 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e nt database is n
36790 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c ot.** encrypted,
367a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
367b0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 ll encrypt it.
367c0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e If pNew==0 or nN
367d0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 ew==0, the.** da
367e0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 tabase is decryp
367f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ted..**.** The c
36800 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 ode to implement
36810 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 this API is not
36820 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 available in th
36830 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 e public release
36840 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a .** of SQLite..*
36850 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
36860 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
36870 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
36880 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
36890 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
368a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
368b0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
368c0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b /* The new k
368d0 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c ey */.);.int sql
368e0 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a 20 ite3_rekey_v2(.
368f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
36900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36910 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 /* Database to b
36920 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 e rekeyed */. c
36930 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 onst char *zDbNa
36940 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a me, /*
36950 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 Name of the dat
36960 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
36970 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
36980 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
36990 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a new key */.);..
369a0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 /*.** Specify th
369b0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 e activation key
369c0 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 62 for a SEE datab
369d0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a ase. Unless .**
369e0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 activated, none
369f0 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 74 of the SEE rout
36a00 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a ines will work..
36a10 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f */.void sqlite3_
36a20 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 activate_see(.
36a30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 const char *zPas
36a40 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f sPhrase /
36a50 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 * Activation phr
36a60 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 ase */.);.#endif
36a70 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f ..#ifdef SQLITE_
36a80 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a ENABLE_CEROD./*.
36a90 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 ** Specify the a
36aa0 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f ctivation key fo
36ab0 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 r a CEROD databa
36ac0 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 se. Unless .**
36ad0 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 activated, none
36ae0 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 of the CEROD rou
36af0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e tines will work.
36b00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 .*/.void sqlite3
36b10 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 _activate_cerod(
36b20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
36b30 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 PassPhrase
36b40 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 /* Activation
36b50 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e phrase */.);.#en
36b60 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
36b70 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
36b80 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
36b90 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 rt Time.**.** Th
36ba0 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 e sqlite3_sleep(
36bb0 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 ) function cause
36bc0 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 s the current th
36bd0 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 read to suspend
36be0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 execution.** for
36bf0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 at least a numb
36c00 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
36c10 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ds specified in
36c20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a its parameter..*
36c30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 *.** If the oper
36c40 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
36c50 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
36c60 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
36c70 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
36c80 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
36c90 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
36ca0 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
36cb0 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
36cc0 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 rest second. The
36cd0 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
36ce0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
36cf0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 actually.** req
36d00 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 uested from the
36d10 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
36d20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
36d30 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c .** ^SQLite impl
36d40 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 ements this inte
36d50 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 rface by calling
36d60 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a the xSleep().**
36d70 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 method of the d
36d80 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
36d90 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 vfs] object. If
36da0 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 the xSleep() me
36db0 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 thod.** of the d
36dc0 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f efault VFS is no
36dd0 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f t implemented co
36de0 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 rrectly, or not
36df0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a implemented at.*
36e00 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 * all, then the
36e10 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
36e20 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 te3_sleep() may
36e30 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 deviate from the
36e40 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 description.**
36e50 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
36e60 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 paragraphs..*/.i
36e70 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 nt sqlite3_sleep
36e80 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 (int);../*.** CA
36e90 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
36ea0 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
36eb0 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69 6c ng Temporary Fil
36ec0 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 es.**.** ^(If th
36ed0 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 is global variab
36ee0 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f le is made to po
36ef0 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
36f00 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 which is.** the
36f10 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 name of a folder
36f20 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f (a.k.a. directo
36f30 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 ry), then all te
36f40 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a mporary files.**
36f50 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c 69 created by SQLi
36f60 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20 te when using a
36f70 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 built-in [sqlite
36f80 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 3_vfs | VFS].**
36f90 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 will be placed i
36fa0 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 n that directory
36fb0 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76 61 .)^ ^If this va
36fc0 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e riable.** is a N
36fd0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
36fe0 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72 6d n SQLite perform
36ff0 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20 61 s a search for a
37000 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a n appropriate.**
37010 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 temporary file
37020 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a directory..**.**
37030 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
37040 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
37050 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
37060 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 in more than one
37070 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 .** thread at a
37080 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 time. It is not
37090 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 safe to read or
370a0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 modify this var
370b0 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 iable.** if a [d
370c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
370d0 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 on] is being use
370e0 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 d at the same ti
370f0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 me in a separate
37100 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 .** thread..** I
37110 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 t is intended th
37120 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
37130 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 be set once.**
37140 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 as part of proce
37150 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
37160 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 n and before any
37170 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
37180 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 e.** routines ha
37190 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 ve been called a
371a0 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 nd that this var
371b0 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 iable remain unc
371c0 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 hanged.** therea
371d0 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 fter..**.** ^The
371e0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
371f0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d ectory pragma] m
37200 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 ay modify this v
37210 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 ariable and caus
37220 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 e.** it to point
37230 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
37240 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
37250 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 3_malloc]. ^Fur
37260 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 thermore,.** the
37270 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
37280 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 ectory pragma] a
37290 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 lways assumes th
372a0 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a at any string.**
372b0 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
372c0 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 ble points to is
372d0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 held in memory
372e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a obtained from .*
372f0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
37300 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d c] and the pragm
37310 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f a may attempt to
37320 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 free that memor
37330 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 y.** using [sqli
37340 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 te3_free]..** He
37350 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 nce, if this var
37360 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 iable is modifie
37370 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 d directly, eith
37380 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a er it should be.
37390 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 ** made NULL or
373a0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
373b0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
373c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
373d0 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 alloc].** or els
373e0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 e the use of the
373f0 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
37400 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 ectory pragma] s
37410 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 hould be avoided
37420 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
37430 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
37440 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
37450 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
37460 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
37470 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
37480 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
37490 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 open] or [sqlite
374a0 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 3_open_v2]. Oth
374b0 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
374c0 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
374d0 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
374e0 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
374f0 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 les may fail. H
37500 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 ere is an.** exa
37510 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 mple of how to d
37520 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b o this using C++
37530 20 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 with the Window
37540 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a s Runtime:.**.**
37550 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
37560 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 e>.** LPCWSTR zP
37570 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 ath = Windows::S
37580 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 torage::Applicat
37590 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 ionData::Current
375a0 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 ->.**
375b0 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 65 72 TemporaryFolder
375c0 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 3b 0a ->Path->Data();.
375d0 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42 75 66 ** char zPathBuf
375e0 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 2b 20 [MAX_PATH +
375f0 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 1];.** memse
37600 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c 20 73 t(zPathBuf, 0, s
37610 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 29 29 izeof(zPathBuf))
37620 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 6f 4d ;.** WideCharToM
37630 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54 46 38 ultiByte(CP_UTF8
37640 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 2c 20 , 0, zPath, -1,
37650 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65 6f 66 zPathBuf, sizeof
37660 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a 20 26 (zPathBuf),.** &
37670 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c 2c 20 nbsp; NULL,
37680 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 74 65 NULL);.** sqlite
37690 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3_temp_directory
376a0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
376b0 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68 42 75 tf("%s", zPathBu
376c0 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 f);.** </pre></b
376d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a 53 51 lockquote>.*/.SQ
376e0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 LITE_EXTERN char
376f0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 *sqlite3_temp_d
37700 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a irectory;../*.**
37710 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 CAPI3REF: Name
37720 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f Of The Folder Ho
37730 6c 64 69 6e 67 20 44 61 74 61 62 61 73 65 20 46 lding Database F
37740 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 iles.**.** ^(If
37750 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 this global vari
37760 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 able is made to
37770 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
37780 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 g which is.** th
37790 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 e name of a fold
377a0 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 er (a.k.a. direc
377b0 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 tory), then all
377c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 0a 2a database files.*
377d0 2a 20 73 70 65 63 69 66 69 65 64 20 77 69 74 68 * specified with
377e0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 a relative path
377f0 6e 61 6d 65 20 61 6e 64 20 63 72 65 61 74 65 64 name and created
37800 20 6f 72 20 61 63 63 65 73 73 65 64 20 62 79 0a or accessed by.
37810 2a 2a 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 ** SQLite when u
37820 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 sing a built-in
37830 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69 74 65 33 windows [sqlite3
37840 5f 76 66 73 20 7c 20 56 46 53 5d 20 77 69 6c 6c _vfs | VFS] will
37850 20 62 65 20 61 73 73 75 6d 65 64 0a 2a 2a 20 74 be assumed.** t
37860 6f 20 62 65 20 72 65 6c 61 74 69 76 65 20 74 6f o be relative to
37870 20 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e that directory.
37880 29 5e 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 )^ ^If this vari
37890 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 0a 2a able is a NULL.*
378a0 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 * pointer, then
378b0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 SQLite assumes t
378c0 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73 65 hat all database
378d0 20 66 69 6c 65 73 20 73 70 65 63 69 66 69 65 64 files specified
378e0 0a 2a 2a 20 77 69 74 68 20 61 20 72 65 6c 61 74 .** with a relat
378f0 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61 72 65 ive pathname are
37900 20 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 65 relative to the
37910 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
37920 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65 20 70 72 ry.** for the pr
37930 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20 74 68 65 ocess. Only the
37940 20 77 69 6e 64 6f 77 73 20 56 46 53 20 6d 61 6b windows VFS mak
37950 65 73 20 75 73 65 20 6f 66 20 74 68 69 73 20 67 es use of this g
37960 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69 61 62 6c lobal.** variabl
37970 65 3b 20 69 74 20 69 73 20 69 67 6e 6f 72 65 64 e; it is ignored
37980 20 62 79 20 74 68 65 20 75 6e 69 78 20 56 46 53 by the unix VFS
37990 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67 ..**.** Changing
379a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
379b0 69 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c is variable whil
379c0 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e e a database con
379d0 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70 nection is.** op
379e0 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e en can result in
379f0 20 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62 a corrupt datab
37a00 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 ase..**.** It is
37a10 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 not safe to rea
37a20 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 d or modify this
37a30 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 variable in mor
37a40 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 e than one.** th
37a50 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 read at a time.
37a60 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
37a70 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
37a80 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a y this variable.
37a90 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 ** if a [databas
37aa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 e connection] is
37ab0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 being used at t
37ac0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 he same time in
37ad0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 a separate.** th
37ae0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 read..** It is i
37af0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 ntended that thi
37b00 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 s variable be se
37b10 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 t once.** as par
37b20 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 t of process ini
37b30 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 tialization and
37b40 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 before any SQLit
37b50 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 e interface.** r
37b60 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 outines have bee
37b70 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 n called and tha
37b80 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 t this variable
37b90 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 remain unchanged
37ba0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a .** thereafter..
37bb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61 **.** ^The [data
37bc0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
37bd0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 pragma] may mod
37be0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
37bf0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 e and cause.** i
37c00 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 t to point to me
37c10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
37c20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
37c30 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f oc]. ^Furthermo
37c40 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61 re,.** the [data
37c50 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
37c60 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 pragma] always
37c70 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 assumes that any
37c80 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 string.** that
37c90 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f this variable po
37ca0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 ints to is held
37cb0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e in memory obtain
37cc0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c ed from .** [sql
37cd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 ite3_malloc] and
37ce0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 the pragma may
37cf0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 attempt to free
37d00 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 that memory.** u
37d10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 sing [sqlite3_fr
37d20 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 ee]..** Hence, i
37d30 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 f this variable
37d40 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 is modified dire
37d50 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 ctly, either it
37d60 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 should be.** mad
37d70 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 e NULL or made t
37d80 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 o point to memor
37d90 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
37da0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d [sqlite3_malloc]
37db0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 .** or else the
37dc0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 use of the [data
37dd0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 _store_directory
37de0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 pragma] should
37df0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 be avoided..*/.S
37e00 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 QLITE_EXTERN cha
37e10 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f r *sqlite3_data_
37e20 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a directory;../*.*
37e30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 * CAPI3REF: Test
37e40 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 For Auto-Commit
37e50 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 Mode.** KEYWORD
37e60 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d S: {autocommit m
37e70 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ode}.**.** ^The
37e80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f sqlite3_get_auto
37e90 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 commit() interfa
37ea0 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ce returns non-z
37eb0 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 ero or.** zero i
37ec0 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 f the given data
37ed0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
37ee0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 is or is not in
37ef0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c autocommit mode,
37f00 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
37f10 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d . ^Autocommit m
37f20 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 ode is on by def
37f30 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f ault..** ^Autoco
37f40 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 mmit mode is dis
37f50 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 abled by a [BEGI
37f60 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a N] statement..**
37f70 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 ^Autocommit mod
37f80 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 e is re-enabled
37f90 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 by a [COMMIT] or
37fa0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a [ROLLBACK]..**.
37fb0 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 ** If certain ki
37fc0 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 nds of errors oc
37fd0 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 cur on a stateme
37fe0 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 nt within a mult
37ff0 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 i-statement.** t
38000 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f ransaction (erro
38010 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 rs including [SQ
38020 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c LITE_FULL], [SQL
38030 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b ITE_IOERR],.** [
38040 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b SQLITE_NOMEM], [
38050 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e SQLITE_BUSY], an
38060 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 d [SQLITE_INTERR
38070 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a UPT]) then the.*
38080 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 * transaction mi
38090 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 ght be rolled ba
380a0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ck automatically
380b0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 . The only way
380c0 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 to.** find out w
380d0 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 hether SQLite au
380e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
380f0 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e ed back the tran
38100 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a saction after.**
38110 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 an error is to
38120 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f use this functio
38130 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 n..**.** If anot
38140 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 her thread chang
38150 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 es the autocommi
38160 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 t status of the
38170 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
38180 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 ection while thi
38190 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e s routine is run
381a0 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ning, then the r
381b0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 eturn value.** i
381c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a s undefined..*/.
381d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f int sqlite3_get_
381e0 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 autocommit(sqlit
381f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
38200 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 I3REF: Find The
38210 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 Database Handle
38220 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 Of A Prepared St
38230 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 atement.**.** ^T
38240 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 he sqlite3_db_ha
38250 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 ndle interface r
38260 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 eturns the [data
38270 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
38280 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 handle.** to wh
38290 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 ich a [prepared
382a0 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e statement] belon
382b0 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 gs. ^The [datab
382c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a ase connection].
382d0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
382e0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
382f0 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 is the same [da
38300 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
38310 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 n].** that was t
38320 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
38330 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c t.** to the [sql
38340 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
38350 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 )] call (or its
38360 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 variants) that w
38370 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 as used to.** cr
38380 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 eate the stateme
38390 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 nt in the first
383a0 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 place..*/.sqlite
383b0 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 3 *sqlite3_db_ha
383c0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d ndle(sqlite3_stm
383d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
383e0 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 3REF: Return The
383f0 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 Filename For A
38400 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
38410 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ion.**.** ^The s
38420 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 qlite3_db_filena
38430 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(D,N) interfac
38440 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e e returns a poin
38450 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d ter to a filenam
38460 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 e.** associated
38470 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 with database N
38480 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e of connection D.
38490 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 ^The main data
384a0 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 base file.** has
384b0 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 the name "main"
384c0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e . If there is n
384d0 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 o attached datab
384e0 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 ase N on the dat
384f0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
38500 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 ion D, or if dat
38510 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d abase N is a tem
38520 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d porary or in-mem
38530 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 ory database, th
38540 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 en.** a NULL poi
38550 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
38560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c ..**.** ^The fil
38570 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 ename returned b
38580 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 y this function
38590 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 is the output of
385a0 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 the.** xFullPat
385b0 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 hname method of
385c0 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 the [VFS]. ^In
385d0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 other words, the
385e0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c filename.** wil
385f0 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 l be an absolute
38600 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 pathname, even
38610 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 if the filename
38620 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 used.** to open
38630 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 the database ori
38640 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 ginally was a UR
38650 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 I or relative pa
38660 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 thname..*/.const
38670 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 char *sqlite3_d
38680 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 b_filename(sqlit
38690 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 e3 *db, const ch
386a0 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f ar *zDbName);../
386b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
386c0 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 etermine if a da
386d0 74 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f tabase is read-o
386e0 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 nly.**.** ^The s
386f0 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e qlite3_db_readon
38700 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 ly(D,N) interfac
38710 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 e returns 1 if t
38720 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a he database N.**
38730 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 of connection D
38740 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 is read-only, 0
38750 20 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 if it is read/w
38760 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e rite, or -1 if N
38770 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e is not.** the n
38780 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 ame of a databas
38790 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 e on connection
387a0 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 D..*/.int sqlite
387b0 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 3_db_readonly(sq
387c0 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 lite3 *db, const
387d0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b char *zDbName);
387e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
387f0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 : Find the next
38800 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
38810 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 nt.**.** ^This i
38820 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
38830 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
38840 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 e next [prepared
38850 20 73 74 6