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 23 69 66 6e 64 65 66 20 53 51 ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 te3.h header.**
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 umber (always 3
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 for.** SQLite3)
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 SION_NUMBER for
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 t is derived. E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 ither Y will.**
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 remented.** and
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 Z will be reset
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 </a>. ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 in of SQLite.**
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 ent system. ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 h of the entire
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 sourceid()],.**
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 ERSION "3
1020: 2e 38 2e 34 22 0a 23 64 65 66 69 6e 65 20 53 51 .8.4".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 38 30 30 34 0a 23 64 65 66 BER 3008004.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 34 2d E_ID "2014-
1070: 30 33 2d 30 36 20 31 38 3a 31 36 3a 34 35 20 63 03-06 18:16:45 c
1080: 30 64 35 34 62 34 65 34 31 63 62 61 38 34 64 63 0d54b4e41cba84dc
1090: 35 39 33 34 65 30 66 63 64 30 33 66 65 34 32 32 5934e0fcd03fe422
10a0: 66 65 35 63 39 32 62 22 0a 0a 2f 2a 0a 2a 2a 20 fe5c92b"../*.**
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 _sourceid.**.**
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a e. ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 rt() statements
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 turned by these
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 d with matching
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 er files..**.**
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 RSION)==0 );.**
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 nt contains the
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 o. ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 ng constant. Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a he DLL. ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e SION_NUMBER]. ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 ceid() function
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 I SQLITE_EXTERN
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51 e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 returns 0 or 1
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 fied option was
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 ompile time. ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 . .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile time option
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 string. ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c inter. ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 ITE_ .** prefix
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 Support for the
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 eoption_used()]
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 ompiled with mut
1c70: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 exing code omitt
1c80: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a ed due to the.**
1c90: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1ca0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d AFE] compile-tim
1cb0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 e option being s
1cc0: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 et to 0..**.** S
1cd0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d QLite can be com
1ce0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 piled with or wi
1cf0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 thout mutexes.
1d00: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c When.** the [SQL
1d10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
1d20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
1d30: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 acro is 1 or 2,
1d40: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 mutexes.** are e
1d50: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 nabled and SQLit
1d60: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e e is threadsafe.
1d70: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 When the.** [S
1d80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1d90: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a ] macro is 0, .*
1da0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 * the mutexes ar
1db0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 e omitted. With
1dc0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c out the mutexes,
1dd0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a it is not safe.
1de0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 ** to use SQLite
1df0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 concurrently fr
1e00: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 om more than one
1e10: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 thread..**.** E
1e20: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 nabling mutexes
1e30: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 incurs a measura
1e40: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ble performance
1e50: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 penalty..** So i
1e60: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 f speed is of ut
1e70: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c most importance,
1e80: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 it makes sense
1e90: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 to disable.** th
1ea0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 e mutexes. But
1eb0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 for maximum safe
1ec0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 ty, mutexes shou
1ed0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a ld be enabled..*
1ee0: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 * ^The default b
1ef0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d ehavior is for m
1f00: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 utexes to be ena
1f10: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 bled..**.** This
1f20: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
1f30: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 e used by an app
1f40: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 lication to make
1f50: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a sure that the.*
1f60: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c * version of SQL
1f70: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c ite that it is l
1f80: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 inking against w
1f90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
1fa0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 .** the desired
1fb0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b setting of the [
1fc0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1fd0: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 E] macro..**.**
1fe0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f This interface o
1ff0: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 nly reports on t
2000: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
2010: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a mutex setting.**
2020: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
2030: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 THREADSAFE] flag
2040: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
2050: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
2060: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
2070: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 FE=1 or =2 then
2080: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 mutexes are enab
2090: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 led by default b
20a0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c ut.** can be ful
20b0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 ly or partially
20c0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 disabled using a
20d0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
20e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 3_config()].** w
20f0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 ith the verbs [S
2100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
2110: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c GLETHREAD], [SQL
2120: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
2130: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b THREAD],.** or [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
2150: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 TEX]. ^(The ret
2160: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 urn value of the
2170: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 .** sqlite3_thre
2180: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
2190: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 n shows only the
21a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 compile-time se
21b0: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 tting of.** thre
21c0: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 ad safety, not a
21d0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e ny run-time chan
21e0: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 ges to that sett
21f0: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 ing made by.** s
2200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e qlite3_config().
2210: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
2220: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
2230: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 e from sqlite3_t
2240: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 hreadsafe().** i
2250: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 s unchanged by c
2260: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
2270: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a config().)^.**.*
2280: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 * See the [threa
2290: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d ding mode] docum
22a0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 entation for add
22b0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
22c0: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ion..*/.SQLITE_A
22d0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 PI int sqlite3_t
22e0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b hreadsafe(void);
22f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2300: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 : Database Conne
2310: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 ction Handle.**
2320: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 KEYWORDS: {datab
2330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 ase connection}
2340: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 {database connec
2350: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 tions}.**.** Eac
2360: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 h open SQLite da
2370: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 tabase is repres
2380: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 ented by a point
2390: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
23a0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 e of.** the opaq
23b0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d ue structure nam
23c0: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 ed "sqlite3". I
23d0: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 t is useful to t
23e0: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 hink of an sqlit
23f0: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 e3.** pointer as
2400: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 an object. The
2410: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
2420: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
2430: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 16()], and.** [s
2440: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
2450: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ] interfaces are
2460: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 its constructor
2470: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f s, and [sqlite3_
2480: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 close()].** and
2490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 [sqlite3_close_v
24a0: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 2()] are its des
24b0: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 tructors. There
24c0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a are many other.
24d0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 ** interfaces (s
24e0: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 uch as.** [sqlit
24f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2500: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 , [sqlite3_creat
2510: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 e_function()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
2530: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 usy_timeout()] t
2540: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 o name but three
2550: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f ) that are metho
2560: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 ds on an.** sqli
2570: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 te3 object..*/.t
2580: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
2590: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a lite3 sqlite3;..
25a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25b0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 64-Bit Integer T
25c0: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ypes.** KEYWORDS
25d0: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 : sqlite_int64 s
25e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a qlite_uint64.**.
25f0: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 ** Because there
2600: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 is no cross-pla
2610: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 tform way to spe
2620: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 cify 64-bit inte
2630: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c ger types.** SQL
2640: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 ite includes typ
2650: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 edefs for 64-bit
2660: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 signed and unsi
2670: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a gned integers..*
2680: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
2690: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 _int64 and sqlit
26a0: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 e3_uint64 are th
26b0: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 e preferred type
26c0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a definitions..**
26d0: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 The sqlite_int6
26e0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 4 and sqlite_uin
26f0: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 t64 types are su
2700: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b pported for back
2710: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 wards.** compati
2720: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a bility only..**.
2730: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2740: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2750: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e _int64 types can
2760: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 store integer v
2770: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e alues.** between
2780: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 -92233720368547
2790: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 75808 and +92233
27a0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 72036854775807 i
27b0: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a nclusive. ^The.
27c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 ** sqlite3_uint6
27d0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 4 and sqlite_uin
27e0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 t64 types can st
27f0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ore integer valu
2800: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 es .** between 0
2810: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 and +1844674407
2820: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 3709551615 inclu
2830: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 sive..*/.#ifdef
2840: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
2850: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 E. typedef SQLI
2860: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 TE_INT64_TYPE sq
2870: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
2880: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 pedef unsigned S
2890: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
28b0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d #elif defined(_M
28c0: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e SC_VER) || defin
28d0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 ed(__BORLANDC__)
28e0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 . typedef __int
28f0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 64 sqlite_int64;
2900: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 . typedef unsig
2910: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 ned __int64 sqli
2920: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 te_uint64;.#else
2930: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 . typedef long
2940: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f long int sqlite_
2950: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
2960: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c unsigned long l
2970: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 ong int sqlite_u
2980: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 int64;.#endif.ty
2990: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 pedef sqlite_int
29a0: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 64 sqlite3_int64
29b0: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 ;.typedef sqlite
29c0: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f _uint64 sqlite3_
29d0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 uint64;../*.** I
29e0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 f compiling for
29f0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 a processor that
2a00: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 lacks floating
2a10: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a point support,.*
2a20: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 * substitute int
2a30: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e eger for floatin
2a40: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 g-point..*/.#ifd
2a50: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 ef SQLITE_OMIT_F
2a60: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 LOATING_POINT.#
2a70: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 define double sq
2a80: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 lite3_int64.#end
2a90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
2aa0: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 EF: Closing A Da
2ab0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
2ac0: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c n.**.** ^The sql
2ad0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 ite3_close() and
2ae0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
2af0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 2() routines are
2b00: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 destructors.**
2b10: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
2b20: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 ] object..** ^Ca
2b30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
2b40: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lose() and sqlit
2b50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 e3_close_v2() re
2b60: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 turn SQLITE_OK i
2b70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 f.** the [sqlite
2b80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 3] object is suc
2b90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f cessfully destro
2ba0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f yed and all asso
2bb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 ciated.** resour
2bc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 ces are dealloca
2bd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ted..**.** ^If t
2be0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2bf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 ection is associ
2c00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 ated with unfina
2c10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a lized prepared.*
2c20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 * statements or
2c30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 unfinished sqlit
2c40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 e3_backup object
2c50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 s then sqlite3_c
2c60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c lose().** will l
2c70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 eave the databas
2c80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 e connection ope
2c90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 n and return [SQ
2ca0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e LITE_BUSY]..** ^
2cb0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 If sqlite3_close
2cc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 _v2() is called
2cd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
2ce0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2cf0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 ents.** and unfi
2d00: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 nished sqlite3_b
2d10: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 ackups, then the
2d20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2d30: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 tion becomes.**
2d40: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d an unusable "zom
2d50: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 bie" which will
2d60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 automatically be
2d70: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 deallocated whe
2d80: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 n the.** last pr
2d90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2da0: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 is finalized or
2db0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 the last sqlite
2dc0: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 3_backup is.** f
2dd0: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 inished. The sq
2de0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2df0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e interface is in
2e00: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 tended for use w
2e10: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 ith.** host lang
2e20: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 uages that are g
2e30: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 arbage collected
2e40: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 , and where the
2e50: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a order in which.*
2e60: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 * destructors ar
2e70: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 e called is arbi
2e80: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 trary..**.** App
2e90: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
2ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
2eb0: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 ze | finalize] a
2ec0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ll [prepared sta
2ed0: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 tements],.** [sq
2ee0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 lite3_blob_close
2ef0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 | close] all [B
2f00: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e LOB handles], an
2f10: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 d .** [sqlite3_b
2f20: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 ackup_finish | f
2f30: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 inish] all [sqli
2f40: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
2f50: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a cts associated.*
2f60: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 * with the [sqli
2f70: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f te3] object prio
2f80: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 r to attempting
2f90: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a to close the obj
2fa0: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c ect. ^If.** sql
2fb0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
2fc0: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b is called on a [
2fd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2fe0: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 ion] that still
2ff0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 has.** outstandi
3000: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ng [prepared sta
3010: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 tements], [BLOB
3020: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 handles], and/or
3030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
3040: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 kup] objects the
3050: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c n it returns SQL
3060: 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 ITE_OK but the d
3070: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
3080: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 f resources is d
3090: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c eferred until al
30a0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
30b0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
30c0: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 andles],.** and
30d0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
30e0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 objects are als
30f0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a o destroyed..**.
3100: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 ** ^If an [sqlit
3110: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 e3] object is de
3120: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 stroyed while a
3130: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
3140: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
3150: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
3160: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
3170: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
3180: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
3190: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
31a0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
31b0: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d lose_v2(C)].** m
31c0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
31d0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
31e0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 or an [sqlite3]
31f0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f object pointer o
3200: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
3210: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
3220: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
3230: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
3240: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
3250: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 and not previou
3260: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e sly closed..** ^
3270: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
3280: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 close() or sqlit
3290: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 e3_close_v2() wi
32a0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
32b0: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
32c0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
32d0: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 p..*/.SQLITE_API
32e0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f int sqlite3_clo
32f0: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 se(sqlite3*);.SQ
3300: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
3310: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 ite3_close_v2(sq
3320: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
3330: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 The type for a c
3340: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
3350: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 ..** This is leg
3360: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 acy and deprecat
3370: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 ed. It is inclu
3380: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ded for historic
3390: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c al.** compatibil
33a0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 ity and is not d
33b0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 ocumented..*/.ty
33c0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 pedef int (*sqli
33d0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f te3_callback)(vo
33e0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 id*,int,char**,
33f0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 char**);../*.**
3400: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 CAPI3REF: One-St
3410: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 ep Query Executi
3420: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a on Interface.**.
3430: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
3440: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
3450: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 is a convenience
3460: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
3470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
3480: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
3490: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
34a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
34b0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 ze()],.** that a
34c0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 llows an applica
34d0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 tion to run mult
34e0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 iple statements
34f0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 of SQL.** withou
3500: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 t having to use
3510: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e a lot of C code.
3520: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
3530: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
3540: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 rface runs zero
3550: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e or more UTF-8 en
3560: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f coded,.** semico
3570: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c lon-separate SQL
3580: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 statements pass
3590: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 ed into its 2nd
35a0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 argument,.** in
35b0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 the context of t
35c0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
35d0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 nection] passed
35e0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a in as its 1st.**
35f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 argument. ^If
3600: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
3610: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 ction of the 3rd
3620: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
3630: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3640: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
3650: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 it is invoked f
3660: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 or each result r
3670: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 ow.** coming out
3680: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 of the evaluate
3690: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
36a0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 . ^The 4th argu
36b0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 ment to.** sqlit
36c0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c e3_exec() is rel
36d0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 ayed through to
36e0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 the 1st argument
36f0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c of each.** call
3700: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e back invocation.
3710: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ^If the callba
3720: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 ck pointer to sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
3740: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f is NULL, then no
3750: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 callback is eve
3760: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 r invoked and re
3770: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a sult rows are.**
3780: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
3790: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 ^If an error occ
37a0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 urs while evalua
37b0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 ting the SQL sta
37c0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 tements passed i
37d0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 nto.** sqlite3_e
37e0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 xec(), then exec
37f0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 ution of the cur
3800: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 rent statement s
3810: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 tops and.** subs
3820: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 equent statement
3830: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 s are skipped.
3840: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 ^If the 5th para
3850: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
3860: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f _exec().** is no
3870: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 t NULL then any
3880: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
3890: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
38a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a mory obtained.**
38b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
38c0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 alloc()] and pas
38d0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 sed back through
38e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
38f0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 er..** To avoid
3900: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 memory leaks, th
3910: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
3920: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c ould invoke [sql
3930: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 ite3_free()].**
3940: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 on error message
3950: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
3960: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 d through the 5t
3970: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a h parameter of.*
3980: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 * of sqlite3_exe
3990: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 c() after the er
39a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
39b0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ng is no longer
39c0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 needed..** ^If t
39d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
39e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
39f0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 () is not NULL a
3a00: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 nd no errors.**
3a10: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 occur, then sqli
3a20: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 te3_exec() sets
3a30: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 the pointer in i
3a40: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 ts 5th parameter
3a50: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f to.** NULL befo
3a60: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
3a70: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 .** ^If an sqlit
3a80: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3a90: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
3aa0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ero, the sqlite3
3ab0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 _exec().** routi
3ac0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ne returns SQLIT
3ad0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 E_ABORT without
3ae0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c invoking the cal
3af0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a lback again and.
3b00: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 ** without runni
3b10: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e ng any subsequen
3b20: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 t SQL statements
3b30: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 ..**.** ^The 2nd
3b40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
3b50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3b60: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
3b70: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 n is the.** numb
3b80: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
3b90: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 the result. ^T
3ba0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
3bb0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
3bc0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 xec().** callbac
3bd0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 k is an array of
3be0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
3bf0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 ings obtained as
3c00: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c if from.** [sql
3c10: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
3c20: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 ()], one for eac
3c30: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 h column. ^If a
3c40: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a n element of a.*
3c50: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 * result row is
3c60: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f NULL then the co
3c70: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 rresponding stri
3c80: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 ng pointer for t
3c90: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
3ca0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
3cb0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
3cc0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d ^The 4th argum
3cd0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 ent to the.** sq
3ce0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
3cf0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 lback is an arra
3d00: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
3d10: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 strings where e
3d20: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 ach.** entry rep
3d30: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 resents the name
3d40: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e of correspondin
3d50: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 g result column
3d60: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 as obtained.** f
3d70: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
3d80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a umn_name()]..**.
3d90: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 ** ^If the 2nd p
3da0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
3db0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 te3_exec() is a
3dc0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 NULL pointer, a
3dd0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e pointer.** to an
3de0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f empty string, o
3df0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 r a pointer that
3e00: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 contains only w
3e10: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 hitespace and/or
3e20: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 .** SQL comment
3e30: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 s, then no SQL s
3e40: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 tatements are ev
3e50: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 aluated and the
3e60: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e database.** is n
3e70: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a ot changed..**.*
3e80: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a * Restrictions:.
3e90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
3ea0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
3eb0: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 on must insure t
3ec0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 hat the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 _exec().**
3ef0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f is a valid and o
3f00: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
3f10: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c nnection]..** <l
3f20: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
3f30: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 on must not clos
3f40: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 e the [database
3f50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
3f60: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 ified by.**
3f70: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
3f80: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
3f90: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 ec() while sqlit
3fa0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e e3_exec() is run
3fb0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 ning..** <li> Th
3fc0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
3fd0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 st not modify th
3fe0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
3ff0: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f text passed into
4000: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 .** the 2nd
4010: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
4020: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 lite3_exec() whi
4030: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 le sqlite3_exec(
4040: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a ) is running..**
4050: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 </ul>.*/.SQLITE
4060: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
4070: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
4080: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40a0: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
40b0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
40c0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40e0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
40f0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
4100: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
4110: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
4120: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
4130: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
4140: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4170: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
4180: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
4190: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
41a0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41c0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
41d0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
41e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
41f0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
4200: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 KEYWORDS: SQLIT
4210: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 E_OK {error code
4220: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a } {error codes}.
4230: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 ** KEYWORDS: {re
4240: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 sult code} {resu
4250: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 lt codes}.**.**
4260: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 Many SQLite func
4270: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 tions return an
4280: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 integer result c
4290: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 ode from the set
42a0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 shown.** here i
42b0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 n order to indic
42c0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 ate success or f
42d0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 ailure..**.** Ne
42e0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 w error codes ma
42f0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
4300: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
4310: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 SQLite..**.** S
4320: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
4330: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 _IOERR_READ | ex
4340: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
4350: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 des],.** [sqlite
4360: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 3_vtab_on_confli
4370: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f ct()] [SQLITE_RO
4380: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 LLBACK | result
4390: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 codes]..*/.#defi
43a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 ne SQLITE_OK
43b0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 0 /* Su
43c0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 ccessful result
43d0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d */./* beginning-
43e0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
43f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4400: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 _ERROR 1
4410: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f /* SQL error o
4420: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 r missing databa
4430: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
4440: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 LITE_INTERNAL
4450: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 2 /* Interna
4460: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e l logic error in
4470: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 SQLite */.#defi
4480: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 ne SQLITE_PERM
4490: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 3 /* Ac
44a0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 cess permission
44b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 e SQLITE_ABORT
44d0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 4 /* Cal
44e0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 lback routine re
44f0: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 quested an abort
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4510: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 TE_BUSY
4520: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 5 /* The datab
4530: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b ase file is lock
4540: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4550: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 LITE_LOCKED
4560: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 6 /* A table
4570: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 in the database
4580: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
4590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d efine SQLITE_NOM
45a0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a EM 7 /*
45b0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c A malloc() fail
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
45d0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 LITE_READONLY
45e0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 8 /* Attempt
45f0: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 to write a read
4600: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f only database */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4620: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 INTERRUPT 9
4630: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 /* Operation te
4640: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 rminated by sqli
4650: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a te3_interrupt()*
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4670: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 _IOERR 10
4680: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f /* Some kind o
4690: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 f disk I/O error
46a0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 occurred */.#de
46b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 fine SQLITE_CORR
46c0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 UPT 11 /*
46d0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 The database dis
46e0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f k image is malfo
46f0: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rmed */.#define
4700: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
4710: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 12 /* Unkno
4720: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c wn opcode in sql
4730: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
4740: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 l() */.#define S
4750: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 QLITE_FULL
4760: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 13 /* Insert
4770: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 ion failed becau
4780: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 se database is f
4790: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ull */.#define S
47a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 QLITE_CANTOPEN
47b0: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 14 /* Unable
47c0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 to open the dat
47d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 abase file */.#d
47e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f efine SQLITE_PRO
47f0: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a TOCOL 15 /*
4800: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 Database lock p
4810: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f rotocol error */
4820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4830: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 EMPTY 16
4840: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 /* Database is
4850: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 empty */.#define
4860: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 SQLITE_SCHEMA
4870: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 17 /* The
4880: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
4890: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 changed */.#defi
48a0: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 ne SQLITE_TOOBIG
48b0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 18 /* St
48c0: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 ring or BLOB exc
48d0: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 eeds size limit
48e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
48f0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 E_CONSTRAINT 19
4900: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 /* Abort due
4910: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 to constraint vi
4920: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 olation */.#defi
4930: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 ne SQLITE_MISMAT
4940: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 CH 20 /* Da
4950: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 ta type mismatch
4960: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4970: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 TE_MISUSE 2
4980: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 1 /* Library u
4990: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 sed incorrectly
49a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
49b0: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 E_NOLFS 22
49c0: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 /* Uses OS fe
49d0: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f atures not suppo
49e0: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a rted on host */.
49f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
4a00: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 UTH 23
4a10: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e /* Authorization
4a20: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 denied */.#defi
4a30: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 ne SQLITE_FORMAT
4a40: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 24 /* Au
4a50: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 xiliary database
4a60: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f format error */
4a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4a80: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 RANGE 25
4a90: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 /* 2nd paramete
4aa0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
4ab0: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a d out of range *
4ac0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4ad0: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 _NOTADB 26
4ae0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 /* File opened
4af0: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 that is not a d
4b00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
4b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
4b20: 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 OTICE 27
4b30: 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 /* Notifications
4b40: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f from sqlite3_lo
4b50: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 g() */.#define S
4b60: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 QLITE_WARNING
4b70: 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 28 /* Warnin
4b80: 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f gs from sqlite3_
4b90: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 log() */.#define
4ba0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 SQLITE_ROW
4bb0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 100 /* sqli
4bc0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 te3_step() has a
4bd0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 nother row ready
4be0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4bf0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 TE_DONE 1
4c00: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 01 /* sqlite3_s
4c10: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 tep() has finish
4c20: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a ed executing */.
4c30: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d /* end-of-error-
4c40: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 codes */../*.**
4c50: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 CAPI3REF: Extend
4c60: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
4c70: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 ** KEYWORDS: {ex
4c80: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
4c90: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 e} {extended err
4ca0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 or codes}.** KEY
4cb0: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 WORDS: {extended
4cc0: 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 result code} {e
4cd0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4ce0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 odes}.**.** In i
4cf0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 ts default confi
4d00: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 guration, SQLite
4d10: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 API routines re
4d20: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 turn one of 26 i
4d30: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 nteger.** [SQLIT
4d40: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f E_OK | result co
4d50: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 des]. However,
4d60: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 experience has s
4d70: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f hown that many o
4d80: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c f.** these resul
4d90: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 t codes are too
4da0: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 coarse-grained.
4db0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f They do not pro
4dc0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 vide as.** much
4dd0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
4de0: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 t problems as pr
4df0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 ogrammers might
4e00: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 like. In an eff
4e10: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 ort to.** addres
4e20: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 s this, newer ve
4e30: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
4e40: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 (version 3.3.8
4e50: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 and later) inclu
4e60: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f de.** support fo
4e70: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 r additional res
4e80: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 ult codes that p
4e90: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 rovide more deta
4ea0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e iled information
4eb0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 .** about errors
4ec0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 . The extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 esult codes are
4ee0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 enabled or disab
4ef0: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 led.** on a per
4f00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
4f10: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 ion basis using
4f20: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
4f30: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
4f40: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a codes()] API..**
4f50: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 .** Some of the
4f60: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 available extend
4f70: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 ed result codes
4f80: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e are listed here.
4f90: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 .** One may expe
4fa0: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ct the number of
4fb0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
4fc0: 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63 72 codes will incr
4fd0: 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69 6d ease.** over tim
4fe0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 e. Software tha
4ff0: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 t uses extended
5000: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f result codes sho
5010: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f uld expect.** to
5020: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 see new result
5030: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 codes in future
5040: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
5050: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 te..**.** The SQ
5060: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 LITE_OK result c
5070: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 ode will never b
5080: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 e extended. It
5090: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 will always.** b
50a0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a e exactly zero..
50b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 E_IOERR_READ
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 E_IOERR | (1<<8)
50f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5100: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
5110: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 D (SQLITE
5120: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 _IOERR | (2<<8))
5130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5140: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 IOERR_WRITE
5150: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5160: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a IOERR | (3<<8)).
5170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5180: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 OERR_FSYNC
5190: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
51a0: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 OERR | (4<<8)).#
51b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
51c0: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 ERR_DIR_FSYNC
51d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
51e0: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 ERR | (5<<8)).#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5200: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 RR_TRUNCATE
5210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5220: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 RR | (6<<8)).#de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
5240: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 R_FSTAT
5250: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
5260: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 R | (7<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5280: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 _UNLOCK
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
52a0: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 | (8<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
52c0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 RDLOCK
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
52e0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
52f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
5300: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
5310: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5320: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e (10<<8)).#defin
5330: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 e SQLITE_IOERR_B
5340: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 LOCKED
5350: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5360: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (11<<8)).#defin
5370: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e e SQLITE_IOERR_N
5380: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 OMEM
5390: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
53a0: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e (12<<8)).#defin
53b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 e SQLITE_IOERR_A
53c0: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 CCESS
53d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
53e0: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e (13<<8)).#defin
53f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
5400: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b HECKRESERVEDLOCK
5410: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5420: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e (14<<8)).#defin
5430: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c e SQLITE_IOERR_L
5440: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 OCK
5450: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5460: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e (15<<8)).#defin
5470: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
5480: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 LOSE
5490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
54a0: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e (16<<8)).#defin
54b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
54c0: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 IR_CLOSE
54d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
54e0: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e (17<<8)).#defin
54f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5500: 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 HMOPEN
5510: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5520: 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e (18<<8)).#defin
5530: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5540: 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 HMSIZE
5550: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5560: 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e (19<<8)).#defin
5570: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5580: 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 HMLOCK
5590: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
55a0: 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e (20<<8)).#defin
55b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
55c0: 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 HMMAP
55d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
55e0: 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (21<<8)).#defin
55f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5600: 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 EEK
5610: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5620: 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e (22<<8)).#defin
5630: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
5640: 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 ELETE_NOENT
5650: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5660: 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e (23<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d e SQLITE_IOERR_M
5680: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 MAP
5690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
56a0: 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e (24<<8)).#defin
56b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 e SQLITE_IOERR_G
56c0: 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 ETTEMPPATH
56d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
56e0: 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e (25<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
5700: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 ONVPATH
5710: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5720: 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e (26<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f e SQLITE_LOCKED_
5740: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 SHAREDCACHE
5750: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 (SQLITE_LOCKED
5760: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 ne SQLITE_BUSY_R
5780: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 ECOVERY
5790: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 (SQLITE_BUSY
57a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 | (1<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f ine SQLITE_BUSY_
57c0: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 SNAPSHOT
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 (SQLITE_BUSY
57e0: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 | (2<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
5800: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 OPEN_NOTEMPDIR
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
5820: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 OPEN | (1<<8)).#
5830: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
5840: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 NTOPEN_ISDIR
5850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
5860: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 NTOPEN | (2<<8))
5870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 CANTOPEN_FULLPAT
5890: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f H (SQLITE_
58a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 CANTOPEN | (3<<8
58b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 E_CANTOPEN_CONVP
58d0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
58e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c E_CANTOPEN | (4<
58f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5900: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 ITE_CORRUPT_VTAB
5910: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
5920: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 ITE_CORRUPT | (1
5930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5940: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 LITE_READONLY_RE
5950: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 COVERY (SQ
5960: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
5970: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
5990: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 CANTLOCK (
59a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
59b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
59c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
59d0: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 Y_ROLLBACK
59e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
59f0: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 Y | (3<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
5a10: 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 NLY_DBMOVED
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
5a30: 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 NLY | (4<<8)).#d
5a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
5a50: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 RT_ROLLBACK
5a60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f (SQLITE_ABO
5a70: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 RT | (2<<8)).#de
5a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5a90: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 TRAINT_CHECK
5aa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5ab0: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 TRAINT | (1<<8))
5ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ad0: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 CONSTRAINT_COMMI
5ae0: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f THOOK (SQLITE_
5af0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c CONSTRAINT | (2<
5b00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5b10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 ITE_CONSTRAINT_F
5b20: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c OREIGNKEY (SQL
5b30: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5b40: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
5b50: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5b60: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 NT_FUNCTION
5b70: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5b80: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 NT | (4<<8)).#de
5b90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5ba0: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 TRAINT_NOTNULL
5bb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5bc0: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 TRAINT | (5<<8))
5bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5be0: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 CONSTRAINT_PRIMA
5bf0: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f RYKEY (SQLITE_
5c00: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c CONSTRAINT | (6<
5c10: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5c20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 ITE_CONSTRAINT_T
5c30: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c RIGGER (SQL
5c40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5c50: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (7<<8)).#define
5c60: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5c70: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 NT_UNIQUE
5c80: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5c90: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 NT | (8<<8)).#de
5ca0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5cb0: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 TRAINT_VTAB
5cc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5cd0: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 TRAINT | (9<<8))
5ce0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5cf0: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 CONSTRAINT_ROWID
5d00: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5d10: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c CONSTRAINT |(10<
5d20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5d30: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 ITE_NOTICE_RECOV
5d40: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c ER_WAL (SQL
5d50: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c ITE_NOTICE | (1<
5d60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5d70: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 ITE_NOTICE_RECOV
5d80: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c ER_ROLLBACK (SQL
5d90: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c ITE_NOTICE | (2<
5da0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5db0: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f ITE_WARNING_AUTO
5dc0: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c INDEX (SQL
5dd0: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 ITE_WARNING | (1
5de0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 <<8))../*.** CAP
5df0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 I3REF: Flags For
5e00: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 File Open Opera
5e10: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
5e20: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 e bit values are
5e30: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
5e40: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 e in the.** 3rd
5e50: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
5e60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
5e70: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 2()] interface a
5e80: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 nd.** in the 4th
5e90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
5ea0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
5eb0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f Open] method..*/
5ec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5ed0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
5ee0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
5ef0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5f00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5f10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5f20: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
5f30: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
5f40: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5f50: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5f70: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
5f80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
5f90: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
5fa0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
5fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5fc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
5fd0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
5fe0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
5ff0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6000: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
6010: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
6020: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6040: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
6050: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
6060: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6080: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
6090: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
60a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
60b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
60c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
60d0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 OPEN_MEMORY
60e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
60f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6100: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6120: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
6130: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
6140: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6160: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
6170: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
6180: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
61a0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
61b0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
61c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
61d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
61e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
61f0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
6200: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6210: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6220: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
6230: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
6240: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6260: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
6270: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
6280: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
62a0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
62b0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
62c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
62e0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6330: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
6340: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
6350: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6360: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6370: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6380: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
6390: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
63a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
63b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
63c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
63d0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
63e0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
63f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
6400: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
6410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6420: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
6430: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
6440: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
6450: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
6460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6470: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
6480: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
6490: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
64a0: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
64b0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
64c0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
64d0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
64e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
64f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
6500: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
6510: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
6520: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 of these.** bit
6530: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
6540: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
6550: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
6560: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
6570: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
6580: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
6590: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
65a0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
65b0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
65c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
65d0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
65e0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
65f0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
6600: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
6610: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6620: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
6630: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
6640: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
6650: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
6660: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
6670: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
6680: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
6690: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
66a0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
66b0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
66c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
66d0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
66e0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
66f0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
6700: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
6710: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
6720: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
6730: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
6740: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
6750: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
6760: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
6770: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
6780: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
6790: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
67a0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
67b0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
67c0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
67d0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
67e0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
67f0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
6800: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
6810: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 RWRITE property
6820: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 means that.** af
6830: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f ter reboot follo
6840: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 wing a crash or
6850: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 power loss, the
6860: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a only bytes in a.
6870: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 ** file that wer
6880: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 e written at the
6890: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 application lev
68a0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 el might have ch
68b0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 anged.** and tha
68c0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 t adjacent bytes
68d0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 , even bytes wit
68e0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 hin the same sec
68f0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 tor are.** guara
6900: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 nteed to be unch
6910: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 anged. The SQLI
6920: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
6930: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a ABLE_WHEN_OPEN.*
6940: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 * flag indicate
6950: 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e that a file cann
6960: 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 ot be deleted wh
6970: 65 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 23 64 65 66 en open..*/.#def
6980: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6990: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
69a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
69b0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
69c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
69d0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 2 0
69e0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
69f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6a00: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 TOMIC1K
6a10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
6a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6a30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
6a50: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
6a60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6a70: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 MIC4K
6a80: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 0x00000010.#
6a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6aa0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 CAP_ATOMIC8K
6ab0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6ac0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 00020.#define SQ
6ad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6ae0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 C16K
6af0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
6b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6b10: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
6b20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6b30: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 080.#define SQLI
6b40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
6b50: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
6b60: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
6b70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6b80: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
6b90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
6ba0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6bb0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6bc0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 L 0x
6bd0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
6be0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e SQLITE_IOCAP_UN
6bf0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
6c00: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a PEN 0x00000800.
6c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6c20: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
6c30: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 VERWRITE 0x00
6c40: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 001000../*.** CA
6c50: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 PI3REF: File Loc
6c60: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a king Levels.**.*
6c70: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e * SQLite uses on
6c80: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 e of these integ
6c90: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
6ca0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d second.** argum
6cb0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 ent to calls it
6cc0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f makes to the xLo
6cd0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b ck() and xUnlock
6ce0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 () methods.** of
6cf0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f an [sqlite3_io_
6d00: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e methods] object.
6d10: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
6d20: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 TE_LOCK_NONE
6d30: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 0.#define
6d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
6d50: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 ED 1.#def
6d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
6d70: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a RESERVED 2.
6d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
6d90: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 OCK_PENDING
6da0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
6db0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
6dc0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 E 4../*.** C
6dd0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f API3REF: Synchro
6de0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c nization Type Fl
6df0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 ags.**.** When S
6e00: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 QLite invokes th
6e10: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 e xSync() method
6e20: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 of an.** [sqlit
6e30: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
6e40: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 bject it uses a
6e50: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a combination of.*
6e60: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 * these integer
6e70: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 values as the se
6e80: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a cond argument..*
6e90: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 *.** When the SQ
6ea0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
6eb0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c LY flag is used,
6ec0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 it means that t
6ed0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 he.** sync opera
6ee0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 tion only needs
6ef0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f to flush data to
6f00: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 mass storage.
6f10: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 Inode.** informa
6f20: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 tion need not be
6f30: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 flushed. If the
6f40: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 lower four bits
6f50: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 of the flag.**
6f60: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
6f70: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d C_NORMAL, that m
6f80: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d eans to use norm
6f90: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e al fsync() seman
6fa0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 tics..** If the
6fb0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
6fc0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e equal SQLITE_SYN
6fd0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 C_FULL, that mea
6fe0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 ns.** to use Mac
6ff0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
7000: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 sync instead of
7010: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 fsync()..**.** D
7020: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 o not confuse th
7030: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f e SQLITE_SYNC_NO
7040: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f RMAL and SQLITE_
7050: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a SYNC_FULL flags.
7060: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 ** with the [PRA
7070: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d GMA synchronous]
7080: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 =NORMAL and [PRA
7090: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d GMA synchronous]
70a0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 =FULL.** setting
70b0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f s. The [synchro
70c0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 nous pragma] det
70d0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c ermines when cal
70e0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 ls to the.** xSy
70f0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 nc VFS method oc
7100: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 cur and applies
7110: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 uniformly across
7120: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a all platforms..
7130: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 ** The SQLITE_SY
7140: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
7150: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 LITE_SYNC_FULL f
7160: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 lags determine h
7170: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 ow.** energetic
7180: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 or rigorous or f
7190: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 orceful the sync
71a0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 operations are
71b0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 and.** only make
71c0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e a difference on
71d0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 Mac OSX for the
71e0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 default SQLite
71f0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d code..** (Third-
7200: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d party VFS implem
7210: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 entations might
7220: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 also make the di
7230: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 stinction.** bet
7240: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 ween SQLITE_SYNC
7250: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
7260: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 TE_SYNC_FULL, bu
7270: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f t among the.** o
7280: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 perating systems
7290: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 natively suppor
72a0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f ted by SQLite, o
72b0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 nly Mac OSX.** c
72c0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 ares about the d
72d0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 ifference.).*/.#
72e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
72f0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 NC_NORMAL
7300: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 0x00002.#define
7310: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
7320: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 L 0x000
7330: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 03.#define SQLIT
7340: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 E_SYNC_DATAONLY
7350: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0x00010../*
7360: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
7370: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 Interface Open
7380: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a File Handle.**.*
7390: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 * An [sqlite3_fi
73a0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 le] object repre
73b0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 sents an open fi
73c0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 le in the .** [s
73d0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 qlite3_vfs | OS
73e0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d interface layer]
73f0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 . Individual OS
7400: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d interface.** im
7410: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 plementations wi
7420: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 ll.** want to su
7430: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 bclass this obje
7440: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 ct by appending
7450: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 additional field
7460: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f s.** for their o
7470: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 wn use. The pMe
7480: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 thods entry is a
7490: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a pointer to an.*
74a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 * [sqlite3_io_me
74b0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 thods] object th
74c0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f at defines metho
74d0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e ds for performin
74e0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 g.** I/O operati
74f0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 ons on the open
7500: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 file..*/.typedef
7510: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
7520: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c file sqlite3_fil
7530: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 e;.struct sqlite
7540: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 3_file {. const
7550: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
7560: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 io_methods *pMet
7570: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 hods; /* Method
7580: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 s for an open fi
7590: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 le */.};../*.**
75a0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
75b0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 erface File Virt
75c0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 ual Methods Obje
75d0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 ct.**.** Every f
75e0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 ile opened by th
75f0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
7600: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 Open] method pop
7610: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 ulates an.** [sq
7620: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
7630: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d ct (or, more com
7640: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 monly, a subclas
7650: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c s of the.** [sql
7660: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
7670: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 t) with a pointe
7680: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
7690: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e of this object.
76a0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
76b0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 defines the meth
76c0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 ods used to perf
76d0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 orm various oper
76e0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 ations.** agains
76f0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 t the open file
7700: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 represented by t
7710: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
7720: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 ] object..**.**
7730: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f If the [sqlite3_
7740: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f vfs.xOpen] metho
7750: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 d sets the sqlit
7760: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
7770: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 element .** to
7780: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
7790: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c er, then the sql
77a0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e ite3_io_methods.
77b0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a xClose method.**
77c0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 may be invoked
77d0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c even if the [sql
77e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
77f0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 reported that it
7800: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a failed. The.**
7810: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 only way to pre
7820: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 vent a call to x
7830: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 Close following
7840: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 a failed [sqlite
7850: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 3_vfs.xOpen].**
7860: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 is for the [sqli
7870: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 te3_vfs.xOpen] t
7880: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 o set the sqlite
7890: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
78a0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 element.** to NU
78b0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c LL..**.** The fl
78c0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ags argument to
78d0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 xSync may be one
78e0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 of [SQLITE_SYNC
78f0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b _NORMAL] or.** [
7900: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
7910: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 ]. The first ch
7920: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d oice is the norm
7930: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 al fsync()..** T
7940: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 he second choice
7950: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 is a Mac OS X s
7960: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 tyle fullsync.
7970: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 The [SQLITE_SYNC
7980: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c _DATAONLY].** fl
7990: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 ag may be ORed i
79a0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 n to indicate th
79b0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 at only the data
79c0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 of the file.**
79d0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 and not its inod
79e0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 e needs to be sy
79f0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nced..**.** The
7a00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 integer values t
7a10: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 o xLock() and xU
7a20: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 nlock() are one
7a30: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c of.** <ul>.** <l
7a40: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f i> [SQLITE_LOCK_
7a50: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b NONE],.** <li> [
7a60: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
7a70: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 ED],.** <li> [SQ
7a80: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 LITE_LOCK_RESERV
7a90: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 ED],.** <li> [SQ
7aa0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
7ab0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b G], or.** <li> [
7ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c SQLITE_LOCK_EXCL
7ad0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e USIVE]..** </ul>
7ae0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 .** xLock() incr
7af0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 eases the lock.
7b00: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 xUnlock() decrea
7b10: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a ses the lock..**
7b20: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 The xCheckReser
7b30: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 vedLock() method
7b40: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 checks whether
7b50: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e any database con
7b60: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 nection,.** eith
7b70: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 er in this proce
7b80: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 ss or in some ot
7b90: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 her process, is
7ba0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 holding a RESERV
7bb0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 ED,.** PENDING,
7bc0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 or EXCLUSIVE loc
7bd0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 k on the file.
7be0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a It returns true.
7bf0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 ** if such a loc
7c00: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c k exists and fal
7c10: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a se otherwise..**
7c20: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e .** The xFileCon
7c30: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 trol() method is
7c40: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 a generic inter
7c50: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 face that allows
7c60: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 custom.** VFS i
7c70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 mplementations t
7c80: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 o directly contr
7c90: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 ol an open file
7ca0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 using the.** [sq
7cb0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
7cc0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ol()] interface.
7cd0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 The second "op
7ce0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e " argument is an
7cf0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f .** integer opco
7d00: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 de. The third a
7d10: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e rgument is a gen
7d20: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 eric pointer int
7d30: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e ended to.** poin
7d40: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 t to a structure
7d50: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 that may contai
7d60: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 n arguments or s
7d70: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f pace in which to
7d80: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e .** write return
7d90: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 values. Potent
7da0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 ial uses for xFi
7db0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 leControl() migh
7dc0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e t be.** function
7dd0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 s to enable bloc
7de0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 king locks with
7df0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 timeouts, to cha
7e00: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 nge the.** locki
7e10: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 ng strategy (for
7e20: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 example to use
7e30: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c dot-file locks),
7e40: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 to inquire.** a
7e50: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 bout the status
7e60: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f of a lock, or to
7e70: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 break stale loc
7e80: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a ks. The SQLite.
7e90: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 ** core reserves
7ea0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 all opcodes les
7eb0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 s than 100 for i
7ec0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 ts own use..** A
7ed0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [SQLITE_FCNTL_L
7ee0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 OCKSTATE | list
7ef0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 of opcodes] less
7f00: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 than 100 is ava
7f10: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 ilable..** Appli
7f20: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 cations that def
7f30: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 ine a custom xFi
7f40: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
7f50: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f should use opco
7f60: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 des.** greater t
7f70: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 han 100 to avoid
7f80: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 conflicts. VFS
7f90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7fa0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 should.** retur
7fb0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 n [SQLITE_NOTFOU
7fc0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e ND] for file con
7fd0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 trol opcodes tha
7fe0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a t they do not.**
7ff0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a recognize..**.*
8000: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a * The xSectorSiz
8010: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 e() method retur
8020: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 ns the sector si
8030: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 ze of the.** dev
8040: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 ice that underli
8050: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 es the file. Th
8060: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 e sector size is
8070: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 the.** minimum
8080: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 write that can b
8090: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 e performed with
80a0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a out disturbing.*
80b0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e * other bytes in
80c0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 the file. The
80d0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
80e0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 istics().** meth
80f0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 od returns a bit
8100: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 vector describi
8110: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 ng behaviors of
8120: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e the.** underlyin
8130: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 g device:.**.**
8140: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
8150: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8160: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 C].** <li> [SQLI
8170: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 TE_IOCAP_ATOMIC5
8180: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 12].** <li> [SQL
8190: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
81a0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 1K].** <li> [SQL
81b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
81c0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 2K].** <li> [SQL
81d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
81e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
81f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8200: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 8K].** <li> [SQL
8210: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8220: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 16K].** <li> [SQ
8230: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8240: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C32K].** <li> [S
8250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
8260: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC64K].** <li> [
8270: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
8280: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 E_APPEND].** <li
8290: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
82a0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c SEQUENTIAL].** <
82b0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 /ul>.**.** The S
82c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
82d0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e IC property mean
82e0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 s that all write
82f0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 s of.** any size
8300: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
8310: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
8320: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a TOMICnnn values.
8330: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 ** mean that wri
8340: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 tes of blocks th
8350: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 at are nnn bytes
8360: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 in size and.**
8370: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 are aligned to a
8380: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 n address which
8390: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 is an integer mu
83a0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e ltiple of.** nnn
83b0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 are atomic. Th
83c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
83d0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 AFE_APPEND value
83e0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 means.** that w
83f0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 hen data is appe
8400: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 nded to a file,
8410: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 the data is appe
8420: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 nded.** first th
8430: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 en the size of t
8440: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e he file is exten
8450: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f ded, never the o
8460: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 ther.** way arou
8470: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f nd. The SQLITE_
8480: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c IOCAP_SEQUENTIAL
8490: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
84a0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 that.** informat
84b0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 ion is written t
84c0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 o disk in the sa
84d0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c me order as call
84e0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 s.** to xWrite()
84f0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 ..**.** If xRead
8500: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 () returns SQLIT
8510: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 E_IOERR_SHORT_RE
8520: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 AD it must also
8530: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 fill.** in the u
8540: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f nread portions o
8550: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 f the buffer wit
8560: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 h zeros. A VFS
8570: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f that.** fails to
8580: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 zero-fill short
8590: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 reads might see
85a0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 m to work. Howe
85b0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 ver,.** failure
85c0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
85d0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 rt reads will ev
85e0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f entually lead to
85f0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 .** database cor
8600: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 ruption..*/.type
8610: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
8620: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 e3_io_methods sq
8630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
8640: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
8650: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 _io_methods {.
8660: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 int iVersion;.
8670: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 int (*xClose)(sq
8680: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8690: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c int (*xRead)(sql
86a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 ite3_file*, void
86b0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c *, int iAmt, sql
86c0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 ite3_int64 iOfst
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 );. int (*xWrit
86e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
86f0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
8700: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
8710: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
8720: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 int (*xTruncate
8730: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8740: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
8750: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 ize);. int (*xS
8760: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ync)(sqlite3_fil
8770: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a e*, int flags);.
8780: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a int (*xFileSiz
8790: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
87a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
87b0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 *pSize);. int (
87c0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f *xLock)(sqlite3_
87d0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
87e0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 nt (*xUnlock)(sq
87f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
8800: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 );. int (*xChec
8810: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 kReservedLock)(s
8820: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8830: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 t *pResOut);. i
8840: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f nt (*xFileContro
8850: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a l)(sqlite3_file*
8860: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a , int op, void *
8870: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 pArg);. int (*x
8880: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 SectorSize)(sqli
8890: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
88a0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 t (*xDeviceChara
88b0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 cteristics)(sqli
88c0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a te3_file*);. /*
88d0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 Methods above a
88e0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 re valid for ver
88f0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 sion 1 */. int
8900: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 (*xShmMap)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 e3_file*, int iP
8920: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 g, int pgsz, int
8930: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a , void volatile*
8940: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
8950: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
8960: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c le*, int offset,
8970: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 int n, int flag
8980: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 s);. void (*xSh
8990: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 mBarrier)(sqlite
89a0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
89b0: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c (*xShmUnmap)(sql
89c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
89d0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f deleteFlag);. /
89e0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 * Methods above
89f0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 are valid for ve
8a00: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 rsion 2 */. int
8a10: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 (*xFetch)(sqlit
8a20: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 e3_file*, sqlite
8a30: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 3_int64 iOfst, i
8a40: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a nt iAmt, void **
8a50: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e pp);. int (*xUn
8a60: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 fetch)(sqlite3_f
8a70: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
8a80: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 t64 iOfst, void
8a90: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 *p);. /* Method
8aa0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 s above are vali
8ab0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 d for version 3
8ac0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e */. /* Addition
8ad0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 al methods may b
8ae0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
8af0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b e releases */.};
8b00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
8b10: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 : Standard File
8b20: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a Control Opcodes.
8b30: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 **.** These inte
8b40: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ger constants ar
8b50: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 e opcodes for th
8b60: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d e xFileControl m
8b70: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 ethod.** of the
8b80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
8b90: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 ods] object and
8ba0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 for the [sqlite3
8bb0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
8bc0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a .** interface..*
8bd0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
8be0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
8bf0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
8c00: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
8c10: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
8c20: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
8c30: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
8c40: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
8c50: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
8c60: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
8c70: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
8c80: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
8c90: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
8ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
8cb0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
8cc0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
8cd0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
8ce0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
8cf0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
8d00: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
8d10: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
8d20: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
8d30: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
8d40: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 testing and only
8d50: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 needs to be sup
8d60: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 ported when SQLI
8d70: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 TE_TEST.** is de
8d80: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a fined..** <ul>.*
8d90: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
8da0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d CNTL_SIZE_HINT]]
8db0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
8dc0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
8dd0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
8de0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 by SQLite to giv
8df0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 e the VFS.** lay
8e00: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 er a hint of how
8e10: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 large the datab
8e20: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 ase file will gr
8e30: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 ow to be during
8e40: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 the.** current t
8e50: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 ransaction. Thi
8e60: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 s hint is not gu
8e70: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 aranteed to be a
8e80: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a ccurate but it.*
8e90: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 * is often close
8ea0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e . The underlyin
8eb0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f g VFS might choo
8ec0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 se to preallocat
8ed0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
8ee0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f le space based o
8ef0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f n this hint in o
8f00: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 rder to help wri
8f10: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 tes to the datab
8f20: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 ase.** file run
8f30: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c faster..**.** <l
8f40: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
8f50: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a _CHUNK_SIZE]].**
8f60: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
8f70: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f TL_CHUNK_SIZE] o
8f80: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
8f90: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 request that th
8fa0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 e VFS.** extends
8fb0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 and truncates t
8fc0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
8fd0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 in chunks of a
8fe0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a size specified.*
8ff0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 * by the user. T
9000: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
9010: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 nt to [sqlite3_f
9020: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 ile_control()] s
9030: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 hould .** point
9040: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 to an integer (t
9050: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e ype int) contain
9060: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e ing the new chun
9070: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a k-size to use.**
9080: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 for the nominat
9090: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c ed database. All
90a0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 ocating database
90b0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c file space in l
90c0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 arge.** chunks (
90d0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d say 1MB at a tim
90e0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 e), may reduce f
90f0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d ile-system fragm
9100: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 entation and.**
9110: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
9120: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 nce on some syst
9130: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ems..**.** <li>[
9140: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
9150: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 LE_POINTER]].**
9160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
9170: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
9180: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
9190: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
91a0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
91b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
91c0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
91d0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
91e0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
91f0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 ection. See the
9200: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
9210: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 ontrol()] docume
9220: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 ntation for.** a
9230: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
9240: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
9250: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9260: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a SYNC_OMITTED]].*
9270: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 * No longer in u
9280: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b se..**.** <li>[[
9290: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
92a0: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 C]].** The [SQLI
92b0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f TE_FCNTL_SYNC] o
92c0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
92d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
92e0: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 SQLite and.** s
92f0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 ent to the VFS i
9300: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 mmediately befor
9310: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 e the xSync meth
9320: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e od is invoked on
9330: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 a.** database f
9340: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 ile descriptor.
9350: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 Or, if the xSync
9360: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 method is not i
9370: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 nvoked .** becau
9380: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 se the user has
9390: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 configured SQLit
93a0: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 e with .** [PRAG
93b0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c MA synchronous |
93c0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e PRAGMA synchron
93d0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 ous=OFF] it is i
93e0: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 nvoked in place
93f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 .** of the xSync
9400: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 method. In most
9410: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e cases, the poin
9420: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ter argument pas
9430: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 sed with.** this
9440: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
9450: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 NULL. However,
9460: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 if the database
9470: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 file is being sy
9480: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 nced.** as part
9490: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 of a multi-datab
94a0: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 ase commit, the
94b0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 argument points
94c0: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 to a nul-termina
94d0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f ted.** string co
94e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 ntaining the tra
94f0: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 nsactions master
9500: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 -journal file na
9510: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a me. VFSes that .
9520: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ** do not need t
9530: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c his signal shoul
9540: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 d silently ignor
9550: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 e this opcode. A
9560: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 pplications .**
9570: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 should not call
9580: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
9590: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 ntrol()] with th
95a0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 is opcode as doi
95b0: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 ng so may .** di
95c0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 srupt the operat
95d0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 ion of the speci
95e0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 alized VFSes tha
95f0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e t do require it.
9600: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 .**.** <li>[[S
9610: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
9620: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a IT_PHASETWO]].**
9630: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
9640: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 TL_COMMIT_PHASET
9650: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 WO] opcode is ge
9660: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
9670: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ly by SQLite.**
9680: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 and sent to the
9690: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e VFS after a tran
96a0: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e saction has been
96b0: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 committed immed
96c0: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 iately.** but be
96d0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 fore the databas
96e0: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 e is unlocked. V
96f0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 FSes that do not
9700: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 need this signa
9710: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 l.** should sile
9720: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 ntly ignore this
9730: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 opcode. Applica
9740: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 tions should not
9750: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
9760: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9770: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f ] with this opco
9780: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d de as doing so m
9790: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a ay disrupt the .
97a0: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 ** operation of
97b0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 the specialized
97c0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 VFSes that do re
97d0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a quire it. .**.*
97e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
97f0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
9800: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 TRY]].** ^The [S
9810: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
9820: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 2_AV_RETRY] opco
9830: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f de is used to co
9840: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 nfigure automati
9850: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 c.** retry count
9860: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 s and intervals
9870: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b for certain disk
9880: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
9890: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f for the.** windo
98a0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 ws [VFS] in orde
98b0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 r to provide rob
98c0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 ustness in the p
98d0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e resence of.** an
98e0: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d ti-virus program
98f0: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 s. By default,
9900: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 the windows VFS
9910: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 will retry file
9920: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 read,.** file wr
9930: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 ite, and file de
9940: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 lete operations
9950: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 up to 10 times,
9960: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 with a delay.**
9970: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e of 25 millisecon
9980: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 ds before the fi
9990: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 rst retry and wi
99a0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 th the delay inc
99b0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e reasing.** by an
99c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d additional 25 m
99d0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 illiseconds with
99e0: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 each subsequent
99f0: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a retry. This.**
9a00: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 opcode allows t
9a10: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 hese two values
9a20: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 (10 retries and
9a30: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 25 milliseconds
9a40: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 of delay).** to
9a50: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 be adjusted. Th
9a60: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 e values are cha
9a70: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 nged for all dat
9a80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
9a90: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 s.** within the
9aa0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 same process. T
9ab0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
9ac0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 pointer to an a
9ad0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 rray of two.** i
9ae0: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 ntegers where th
9af0: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 e first integer
9b00: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 i the new retry
9b10: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 count and the se
9b20: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 cond.** integer
9b30: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 is the delay. I
9b40: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 f either integer
9b50: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
9b60: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a en the setting.*
9b70: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 * is not changed
9b80: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 but instead the
9b90: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
9ba0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 that setting is
9bb0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 written.** into
9bc0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c the array entry,
9bd0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 allowing the cu
9be0: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 rrent retry sett
9bf0: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e ings to be.** in
9c00: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 terrogated. The
9c10: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 zDbName paramet
9c20: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a er is ignored..*
9c30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9c40: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
9c50: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 WAL]].** ^The [S
9c60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
9c70: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 IST_WAL] opcode
9c80: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f is used to set o
9c90: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 r query the.** p
9ca0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c ersistent [WAL |
9cb0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 Write Ahead Log
9cc0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 ] setting. By d
9cd0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 efault, the auxi
9ce0: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 liary.** write a
9cf0: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 head log and sha
9d00: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 red memory files
9d10: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 used for transa
9d20: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a ction control.**
9d30: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c are automatical
9d40: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ly deleted when
9d50: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 the latest conne
9d60: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 ction to the dat
9d70: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e abase.** closes.
9d80: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 Setting persis
9d90: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 tent WAL mode ca
9da0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 uses those files
9db0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 to persist afte
9dc0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 r.** close. Per
9dd0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 sisting the file
9de0: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e s is useful when
9df0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 other processes
9e00: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 that do not.**
9e10: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 have write permi
9e20: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 ssion on the dir
9e30: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e ectory containin
9e40: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 g the database f
9e50: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 ile want.** to r
9e60: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 ead the database
9e70: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 file, as the WA
9e80: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d L and shared mem
9e90: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 ory files must e
9ea0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 xist.** in order
9eb0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
9ec0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 e to be readable
9ed0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 . The fourth pa
9ee0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 rameter to.** [s
9ef0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9f00: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 rol()] for this
9f10: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 opcode should be
9f20: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
9f30: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 integer..** Tha
9f40: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 t integer is 0 t
9f50: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 o disable persis
9f60: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 tent WAL mode or
9f70: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 1 to enable per
9f80: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d sistent.** WAL m
9f90: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
9fa0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
9fb0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
9fc0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
9fd0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 ent.** WAL persi
9fe0: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a stence setting..
9ff0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a000: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
a010: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a FE_OVERWRITE]].*
a020: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a030: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
a040: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
a050: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
a060: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
a070: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 persistent "powe
a080: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 rsafe-overwrite"
a090: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 or "PSOW" setti
a0a0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 ng. The PSOW se
a0b0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 tting.** determi
a0c0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f nes the [SQLITE_
a0d0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
a0e0: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f OVERWRITE] bit o
a0f0: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 f the.** xDevice
a100: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
a110: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 methods. The fou
a120: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
a130: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a140: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
a150: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
a160: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
a170: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
a180: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
a190: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
a1a0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 zero-damage mode
a1b0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
a1c0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d zero-damage.** m
a1d0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 ode. If the int
a1e0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e eger is -1, then
a1f0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 it is overwritt
a200: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 en with the curr
a210: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 ent.** zero-dama
a220: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e ge mode setting.
a230: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
a240: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
a250: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 ITE]].** ^The [S
a260: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
a270: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 WRITE] opcode is
a280: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
a290: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 te after opening
a2a0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e .** a write tran
a2b0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 saction to indic
a2c0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 ate that, unless
a2d0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 it is rolled ba
a2e0: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 ck for some.** r
a2f0: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 eason, the entir
a300: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
a310: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 will be overwrit
a320: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 ten by the curre
a330: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 nt .** transacti
a340: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 on. This is used
a350: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 by VACUUM opera
a360: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tions..**.** <li
a370: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
a380: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 VFSNAME]].** ^Th
a390: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
a3a0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 VFSNAME] opcode
a3b0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
a3c0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 btain the names
a3d0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 of.** all [VFSes
a3e0: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 ] in the VFS sta
a3f0: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 ck. The names a
a400: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 re of all VFS sh
a410: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 ims and the.** f
a420: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 inal bottom-leve
a430: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 l VFS are writte
a440: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 n into memory ob
a450: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 tained from .**
a460: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
a470: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c )] and the resul
a480: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 t is stored in t
a490: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a4a0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f e.** that the fo
a4b0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f urth parameter o
a4c0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f f [sqlite3_file_
a4d0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 control()] point
a4e0: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c s to..** The cal
a4f0: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ler is responsib
a500: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 le for freeing t
a510: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 he memory when d
a520: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a one. As with.**
a530: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f all file-contro
a540: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 l actions, there
a550: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 is no guarantee
a560: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 that this will
a570: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 actually.** do a
a580: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 nything. Caller
a590: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c s should initial
a5a0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 ize the char* va
a5b0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c riable to a NULL
a5c0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 .** pointer in c
a5d0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f ase this file-co
a5e0: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 ntrol is not imp
a5f0: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 lemented. This
a600: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
a610: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
a620: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f diagnostic use o
a630: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b nly..**.** <li>[
a640: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
a650: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 AGMA]].** ^Whene
a660: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 ver a [PRAGMA] s
a670: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 tatement is pars
a680: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 ed, an [SQLITE_F
a690: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a CNTL_PRAGMA] .**
a6a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
a6b0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 sent to the ope
a6c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d n [sqlite3_file]
a6d0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f object correspo
a6e0: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 nding.** to the
a6f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f database file to
a700: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d which the pragm
a710: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 a statement refe
a720: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e rs. ^The argumen
a730: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c t.** to the [SQL
a740: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a750: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
a760: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a s an array of.**
a770: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
a780: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e ings (char**) in
a790: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e which the secon
a7a0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 d element of the
a7b0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 array.** is the
a7c0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 name of the pra
a7d0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 gma and the thir
a7e0: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 d element is the
a7f0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
a800: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 .** pragma or NU
a810: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 LL if the pragma
a820: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 has no argument
a830: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 . ^The handler
a840: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 for an.** [SQLIT
a850: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
a860: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e file control can
a870: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 optionally make
a880: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 the first eleme
a890: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 nt.** of the cha
a8a0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 r** argument poi
a8b0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f nt to a string o
a8c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
a8d0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d lite3_mprintf()]
a8e0: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 .** or the equiv
a8f0: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 alent and that s
a900: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d tring will becom
a910: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of
a920: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a the pragma or.**
a930: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
a940: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 ge if the pragma
a950: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a fails. ^If the.
a960: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
a970: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
a980: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 ntrol returns [S
a990: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
a9a0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a then normal .**
a9b0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 [PRAGMA] proces
a9c0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 sing continues.
a9d0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
a9e0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a _FCNTL_PRAGMA].*
a9f0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 * file control r
aa00: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
aa10: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 K], then the par
aa20: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 ser assumes that
aa30: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 the.** VFS has
aa40: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 handled the PRAG
aa50: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 MA itself and th
aa60: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 e parser generat
aa70: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 es a no-op.** pr
aa80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
aa90: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 . ^If the [SQLI
aaa0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
aab0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
aac0: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 turns.** any res
aad0: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 ult code other t
aae0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 han [SQLITE_OK]
aaf0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f or [SQLITE_NOTFO
ab00: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 UND], that means
ab10: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 .** that the VFS
ab20: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 encountered an
ab30: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 error while hand
ab40: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 ling the [PRAGMA
ab50: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d ] and the.** com
ab60: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 pilation of the
ab70: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 PRAGMA fails wit
ab80: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 h an error. ^Th
ab90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
aba0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
abb0: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 control occurs a
abc0: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 t the beginning
abd0: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d of pragma statem
abe0: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 ent analysis and
abf0: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c so.** it is abl
ac00: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 e to override bu
ac10: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 ilt-in [PRAGMA]
ac20: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
ac30: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
ac40: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 CNTL_BUSYHANDLER
ac50: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 ]].** ^The [SQLI
ac60: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e TE_FCNTL_BUSYHAN
ac70: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f DLER].** file-co
ac80: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 ntrol may be inv
ac90: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f oked by SQLite o
aca0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
acb0: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 ile handle.** sh
acc0: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 ortly after it i
acd0: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 s opened in orde
ace0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 r to provide a c
acf0: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 ustom VFS with a
ad00: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 ccess.** to the
ad10: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 connections busy
ad20: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 -handler callbac
ad30: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 k. The argument
ad40: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 is of type (void
ad50: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 **).** - an arr
ad60: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 ay of two (void
ad70: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 *) values. The f
ad80: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 irst (void *) ac
ad90: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a tually points.**
ada0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f to a function o
adb0: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 f type (int (*)(
adc0: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 void *)). In ord
add0: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 er to invoke the
ade0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
adf0: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 busy-handler, th
ae00: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 is function shou
ae10: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ld be invoked wi
ae20: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 th the second (v
ae30: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 oid *) in.** the
ae40: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e array as the on
ae50: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 ly argument. If
ae60: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a it returns non-z
ae70: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 ero, then the op
ae80: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c eration.** shoul
ae90: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 d be retried. If
aea0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f it returns zero
aeb0: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 , the custom VFS
aec0: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 should abandon
aed0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f the.** current o
aee0: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 peration..**.**
aef0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
af00: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d TL_TEMPFILENAME]
af10: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f ].** ^Applicatio
af20: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 n can invoke the
af30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [SQLITE_FCNTL_T
af40: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c EMPFILENAME] fil
af50: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 e-control.** to
af60: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 have SQLite gene
af70: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 rate a.** tempor
af80: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 ary filename usi
af90: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f ng the same algo
afa0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f rithm that is fo
afb0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 llowed to genera
afc0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 te.** temporary
afd0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 filenames for TE
afe0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 MP tables and ot
aff0: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 her internal use
b000: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d s. The.** argum
b010: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 ent should be a
b020: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c char** which wil
b030: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 l be filled with
b040: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a the filename.**
b050: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
b060: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
b070: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
b080: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c oc()]. The call
b090: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 er should.** inv
b0a0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 oke [sqlite3_fre
b0b0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 e()] on the resu
b0c0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 lt to avoid a me
b0d0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a mory leak..**.**
b0e0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b0f0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a NTL_MMAP_SIZE]].
b100: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
b110: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 CNTL_MMAP_SIZE]
b120: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 file control is
b130: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 used to query or
b140: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 set the.** maxi
b150: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 mum number of by
b160: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 tes that will be
b170: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 used for memory
b180: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 -mapped I/O..**
b190: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
b1a0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 a pointer to a v
b1b0: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c alue of type sql
b1c0: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a ite3_int64 that.
b1d0: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 ** is an advisor
b1e0: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 y maximum number
b1f0: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
b200: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 file to memory
b210: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 map. The.** poi
b220: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 nter is overwrit
b230: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 ten with the old
b240: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d value. The lim
b250: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 it is not change
b260: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 d if.** the valu
b270: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 e originally poi
b280: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 nted to is negat
b290: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 ive, and so the
b2a0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a current limit .*
b2b0: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 * can be queried
b2c0: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 by passing in a
b2d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 pointer to a ne
b2e0: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 gative number.
b2f0: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e This.** file-con
b300: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 trol is used int
b310: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 ernally to imple
b320: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 ment [PRAGMA mma
b330: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c p_size]..**.** <
b340: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
b350: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 L_TRACE]].** The
b360: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [SQLITE_FCNTL_T
b370: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 RACE] file contr
b380: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 ol provides advi
b390: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e sory information
b3a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 .** to the VFS a
b3b0: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 bout what the hi
b3c0: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 gher layers of t
b3d0: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 he SQLite stack
b3e0: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 are doing..** Th
b3f0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 is file control
b400: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 is used by some
b410: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 VFS activity tra
b420: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a cing [shims]..**
b430: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
b440: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
b450: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 ed string. High
b460: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 er layers in the
b470: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b .** SQLite stack
b480: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e may generate in
b490: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 stances of this
b4a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a file control if.
b4b0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 ** the [SQLITE_U
b4c0: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 SE_FCNTL_TRACE]
b4d0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
b4e0: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a ion is enabled..
b4f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
b500: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
b510: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ED]].** The [SQL
b520: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f ITE_FCNTL_HAS_MO
b530: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f VED] file contro
b540: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 l interprets its
b550: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a argument as a.*
b560: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 * pointer to an
b570: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 integer and it w
b580: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 rites a boolean
b590: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 into that intege
b5a0: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f r depending.** o
b5b0: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 n whether or not
b5c0: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 the file has be
b5d0: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 en renamed, move
b5e0: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 d, or deleted si
b5f0: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 nce it.** was fi
b600: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a rst opened..**.*
b610: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </ul>.*/.#defi
b620: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
b630: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 LOCKSTATE
b640: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
b650: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 e SQLITE_GET_LOC
b660: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 KPROXYFILE
b670: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
b680: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b SQLITE_SET_LOCK
b690: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 PROXYFILE
b6a0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
b6b0: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e SQLITE_LAST_ERRN
b6c0: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 O
b6d0: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 4.#define S
b6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
b6f0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 _HINT
b700: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
b710: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
b720: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 _SIZE
b730: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 6.#define SQL
b740: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
b750: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 OINTER
b760: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
b770: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d TE_FCNTL_SYNC_OM
b780: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 ITTED
b790: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
b7a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
b7b0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 _RETRY
b7c0: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
b7d0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 _FCNTL_PERSIST_W
b7e0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 AL 10
b7f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b800: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 FCNTL_OVERWRITE
b810: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 11.
b820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
b830: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 CNTL_VFSNAME
b840: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 12.#
b850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
b860: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 NTL_POWERSAFE_OV
b870: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 ERWRITE 13.#d
b880: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
b890: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 TL_PRAGMA
b8a0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 14.#de
b8b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
b8c0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 L_BUSYHANDLER
b8d0: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 15.#def
b8e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
b8f0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 _TEMPFILENAME
b900: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 16.#defi
b910: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
b920: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 MMAP_SIZE
b930: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 18.#defin
b940: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 e SQLITE_FCNTL_T
b950: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 RACE
b960: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 19.#define
b970: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 SQLITE_FCNTL_HA
b980: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 S_MOVED
b990: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 20.#define
b9a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e SQLITE_FCNTL_SYN
b9b0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 C
b9c0: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 21.#define S
b9d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
b9e0: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 IT_PHASETWO
b9f0: 20 20 20 32 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 22../*.** CAP
ba00: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e I3REF: Mutex Han
ba10: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 dle.**.** The mu
ba20: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 tex module withi
ba30: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 n SQLite defines
ba40: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
ba50: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 to be an.** abs
ba60: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 tract type for a
ba70: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 mutex object.
ba80: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
ba90: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 never looks.** a
baa0: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 t the internal r
bab0: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 epresentation of
bac0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 an [sqlite3_mut
bad0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a ex]. It only.**
bae0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e deals with poin
baf0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c ters to the [sql
bb00: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 ite3_mutex] obje
bb10: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 ct..**.** Mutexe
bb20: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 s are created us
bb30: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
bb40: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a ex_alloc()]..*/.
bb50: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
bb60: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c qlite3_mutex sql
bb70: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a ite3_mutex;../*.
bb80: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
bb90: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 Interface Object
bba0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
bbb0: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ce of the sqlite
bbc0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 3_vfs object def
bbd0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 ines the interfa
bbe0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 ce between.** th
bbf0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e e SQLite core an
bc00: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 d the underlying
bc10: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
bc20: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a m. The "vfs".**
bc30: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 in the name of
bc40: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 the object stand
bc50: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 s for "virtual f
bc60: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 ile system". Se
bc70: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 e.** the [VFS |
bc80: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f VFS documentatio
bc90: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 n] for further i
bca0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
bcb0: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * The value of t
bcc0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c he iVersion fiel
bcd0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 d is initially 1
bce0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 but may be larg
bcf0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 er in.** future
bd00: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
bd10: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 te. Additional
bd20: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
bd30: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a pended to this.*
bd40: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 * object when th
bd50: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 e iVersion value
bd60: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 is increased.
bd70: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 Note that the st
bd80: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 ructure.** of th
bd90: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
bda0: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 ject changes in
bdb0: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 the transaction
bdc0: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 between.** SQLit
bdd0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 e version 3.5.9
bde0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 and 3.6.0 and ye
bdf0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 t the iVersion f
be00: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 ield was not.**
be10: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 modified..**.**
be20: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 The szOsFile fie
be30: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f ld is the size o
be40: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 f the subclassed
be50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a [sqlite3_file].
be60: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 ** structure use
be70: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 d by this VFS.
be80: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 mxPathname is th
be90: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
bea0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d of.** a pathnam
beb0: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a e in this VFS..*
bec0: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 *.** Registered
bed0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
bee0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 cts are kept on
bef0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f a linked list fo
bf00: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 rmed by.** the p
bf10: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 Next pointer. T
bf20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
bf30: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 register()].** a
bf40: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f nd [sqlite3_vfs_
bf50: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e unregister()] in
bf60: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 terfaces manage
bf70: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 this list.** in
bf80: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 a thread-safe wa
bf90: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 y. The [sqlite3
bfa0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 _vfs_find()] int
bfb0: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 erface.** search
bfc0: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 es the list. Ne
bfd0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 ither the applic
bfe0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 ation code nor t
bff0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d he VFS.** implem
c000: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 entation should
c010: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f use the pNext po
c020: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
c030: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 pNext field is
c040: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 the only field i
c050: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
c060: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 s.** structure t
c070: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
c080: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 ever modify. SQ
c090: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 Lite will only a
c0a0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 ccess.** or modi
c0b0: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 fy this field wh
c0c0: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 ile holding a pa
c0d0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 rticular static
c0e0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 mutex..** The ap
c0f0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
c100: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e never modify an
c110: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 ything within th
c120: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
c130: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 object once the
c140: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e object has been
c150: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a registered..**.
c160: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 ** The zName fie
c170: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d ld holds the nam
c180: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 e of the VFS mod
c190: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d ule. The name m
c1a0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 ust.** be unique
c1b0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 across all VFS
c1c0: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b modules..**.** [
c1d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
c1e0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 en]].** ^SQLite
c1f0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
c200: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
c210: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
c220: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 .** is either a
c230: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 NULL pointer or
c240: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a string obtained.
c250: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 ** from xFullPat
c260: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 hname() with an
c270: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 optional suffix
c280: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 added..** ^If a
c290: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 suffix is added
c2a0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 to the zFilename
c2b0: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 parameter, it w
c2c0: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f ill.** consist o
c2d0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 f a single "-" c
c2e0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 haracter followe
c2f0: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 d by no more tha
c300: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d n.** 11 alphanum
c310: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 eric and/or "-"
c320: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e characters..** ^
c330: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 SQLite further g
c340: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a uarantees that.*
c350: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c * the string wil
c360: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
c370: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
c380: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
c390: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 lled. Because of
c3a0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
c3b0: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b ntence,.** the [
c3c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 sqlite3_file] ca
c3d0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 n safely store a
c3e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
c3f0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 ** filename if i
c400: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d t needs to remem
c410: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ber the filename
c420: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e for some reason
c430: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c ..** If the zFil
c440: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
c450: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 to xOpen is a NU
c460: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
c470: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e xOpen.** must in
c480: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d vent its own tem
c490: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 porary name for
c4a0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e the file. ^When
c4b0: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 ever the .** xFi
c4c0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
c4d0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c is NULL it will
c4e0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 also be the cas
c4f0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c e that the.** fl
c500: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 ags parameter wi
c510: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ll include [SQLI
c520: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
c530: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 CLOSE]..**.** Th
c540: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
c550: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c to xOpen() incl
c560: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 udes all bits se
c570: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 t in.** the flag
c580: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 s argument to [s
c590: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
c5a0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 ]. Or if [sqlit
c5b0: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 e3_open()].** or
c5c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
c5d0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 ()] is used, the
c5e0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 n flags includes
c5f0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 at least.** [SQ
c600: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
c610: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
c620: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a PEN_CREATE]. .**
c630: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e If xOpen() open
c640: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e s a file read-on
c650: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 ly then it sets
c660: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a *pOutFlags to.**
c670: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
c680: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e _OPEN_READONLY].
c690: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 Other bits in
c6a0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 *pOutFlags may b
c6b0: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 e set..**.** ^(S
c6c0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 QLite will also
c6d0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
c6e0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
c6f0: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a o the xOpen().**
c700: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 call, depending
c710: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 on the object b
c720: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a eing opened:.**.
c730: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
c740: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
c750: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 IN_DB].** <li>
c760: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
c770: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c N_JOURNAL].** <l
c780: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
c790: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _TEMP_DB].** <li
c7a0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
c7b0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a TEMP_JOURNAL].**
c7c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
c7d0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
c7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
c7f0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
c800: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
c810: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
c820: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
c830: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
c840: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a WAL].** </ul>)^.
c850: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 **.** The file I
c860: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f /O implementatio
c870: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 n can use the ob
c880: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 ject type flags
c890: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 to.** change the
c8a0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 way it deals wi
c8b0: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 th files. For e
c8c0: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
c8d0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 cation.** that d
c8e0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f oes not care abo
c8f0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 ut crash recover
c900: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 y or rollback mi
c910: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 ght make.** the
c920: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 open of a journa
c930: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 l file a no-op.
c940: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 Writes to this
c950: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a journal would.**
c960: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c also be no-ops,
c970: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 and any attempt
c980: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 to read the jou
c990: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 rnal would retur
c9a0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 n.** SQLITE_IOER
c9b0: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 R. Or the imple
c9c0: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 mentation might
c9d0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 recognize that a
c9e0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c database.** fil
c9f0: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 e will be doing
ca00: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 page-aligned sec
ca10: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 tor reads and wr
ca20: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d ites in a random
ca30: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 .** order and se
ca40: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 t up its I/O sub
ca50: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 system according
ca60: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ly..**.** SQLite
ca70: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 might also add
ca80: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
ca90: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
caa0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a e xOpen method:.
cab0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
cac0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
cad0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
cae0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
caf0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a PEN_EXCLUSIVE].*
cb00: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
cb10: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
cb20: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c ELETEONCLOSE] fl
cb30: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c ag means the fil
cb40: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 e should be.** d
cb50: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 eleted when it i
cb60: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 s closed. ^The
cb70: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
cb80: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 ETEONCLOSE].** w
cb90: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 ill be set for T
cba0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e EMP databases an
cbb0: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 d their journals
cbc0: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 , transient.** d
cbd0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 atabases, and su
cbe0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
cbf0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
cc00: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c EN_EXCLUSIVE] fl
cc10: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 ag is always use
cc20: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e d in conjunction
cc30: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 .** with the [SQ
cc40: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
cc50: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 ] flag, which ar
cc60: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a e both directly.
cc70: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 ** analogous to
cc80: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f the O_EXCL and O
cc90: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 _CREAT flags of
cca0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 the POSIX open()
ccb0: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 .** API. The SQ
ccc0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
ccd0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 IVE flag, when p
cce0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a aired with the .
ccf0: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ** SQLITE_OPEN_C
cd00: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 REATE, is used t
cd10: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 o indicate that
cd20: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 file should alwa
cd30: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 ys.** be created
cd40: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 , and that it is
cd50: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 an error if it
cd60: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a already exists..
cd70: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c ** It is <i>not<
cd80: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 /i> used to indi
cd90: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 cate the file sh
cda0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a ould be opened .
cdb0: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 ** for exclusive
cdc0: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e access..**.** ^
cdd0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c At least szOsFil
cde0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 e bytes of memor
cdf0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 y are allocated
ce00: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 by SQLite.** to
ce10: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 hold the [sqlit
ce20: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 e3_file] structu
ce30: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 re passed as the
ce40: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 third.** argume
ce50: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 nt to xOpen. Th
ce60: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 e xOpen method d
ce70: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a oes not have to.
ce80: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 ** allocate the
ce90: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 structure; it sh
cea0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 ould just fill i
ceb0: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 t in. Note that
cec0: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 .** the xOpen me
ced0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 thod must set th
cee0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
cef0: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 Methods to eithe
cf00: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 r.** a valid [sq
cf10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
cf20: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e ] object or to N
cf30: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 ULL. xOpen must
cf40: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e do.** this even
cf50: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 if the open fai
cf60: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 ls. SQLite expe
cf70: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c cts that the sql
cf80: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
cf90: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 ds.** element wi
cfa0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 ll be valid afte
cfb0: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 r xOpen returns
cfc0: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
cfd0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 e success.** or
cfe0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 failure of the x
cff0: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a Open call..**.**
d000: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
d010: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 Access]].** ^The
d020: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
d030: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 to xAccess() may
d040: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 be [SQLITE_ACCE
d050: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f SS_EXISTS].** to
d060: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 test for the ex
d070: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c istence of a fil
d080: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
d090: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 CESS_READWRITE]
d0a0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 to.** test wheth
d0b0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 er a file is rea
d0c0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
d0d0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
d0e0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 CCESS_READ].** t
d0f0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 o test whether a
d100: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 file is at leas
d110: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 t readable. Th
d120: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a e file can be a.
d130: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a ** directory..**
d140: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
d150: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 always allocate
d160: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 at least mxPath
d170: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 name+1 bytes for
d180: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 the.** output b
d190: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e uffer xFullPathn
d1a0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 ame. The exact
d1b0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 size of the outp
d1c0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 ut buffer.** is
d1d0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 also passed as a
d1e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f parameter to bo
d1f0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 th methods. If
d200: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 the output buffe
d210: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 r.** is not larg
d220: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 e enough, [SQLIT
d230: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 E_CANTOPEN] shou
d240: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
d250: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a Since this is.**
d260: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 handled as a fa
d270: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c tal error by SQL
d280: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 ite, vfs impleme
d290: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ntations should
d2a0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 endeavor.** to p
d2b0: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 revent this by s
d2c0: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d etting mxPathnam
d2d0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e e to a sufficien
d2e0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e tly large value.
d2f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 .**.** The xRand
d300: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 omness(), xSleep
d310: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 (), xCurrentTime
d320: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 (), and xCurrent
d330: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 TimeInt64().** i
d340: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f nterfaces are no
d350: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 t strictly a par
d360: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 t of the filesys
d370: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 tem, but they ar
d380: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e e.** included in
d390: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 the VFS structu
d3a0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e re for completen
d3b0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e ess..** The xRan
d3c0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 domness() functi
d3d0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 on attempts to r
d3e0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 eturn nBytes byt
d3f0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 es.** of good-qu
d400: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 ality randomness
d410: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 into zOut. The
d420: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
d430: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e .** the actual n
d440: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
d450: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 f randomness obt
d460: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 ained..** The xS
d470: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 leep() method ca
d480: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 uses the calling
d490: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 thread to sleep
d4a0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 for at.** least
d4b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d the number of m
d4c0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 icroseconds give
d4d0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e n. ^The xCurren
d4e0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f tTime().** metho
d4f0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 d returns a Juli
d500: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f an Day Number fo
d510: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 r the current da
d520: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a te and time as.*
d530: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 * a floating poi
d540: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 nt value..** ^Th
d550: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
d560: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 t64() method ret
d570: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 urns, as an inte
d580: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a ger, the Julian.
d590: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 ** Day Number mu
d5a0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 ltiplied by 8640
d5b0: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 0000 (the number
d5c0: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
d5d0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 in .** a 24-hou
d5e0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 r day). .** ^SQ
d5f0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
d600: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
d610: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 t64() method to
d620: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a get the current.
d630: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 ** date and time
d640: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 if that method
d650: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 is available (if
d660: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f iVersion is 2 o
d670: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e r .** greater an
d680: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 d the function p
d690: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
d6a0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c LL) and will fal
d6b0: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 l back.** to xCu
d6c0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 rrentTime() if x
d6d0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
d6e0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c () is unavailabl
d6f0: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 e..**.** ^The xS
d700: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 etSystemCall(),
d710: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xGetSystemCall()
d720: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 , and xNestSyste
d730: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 mCall() interfac
d740: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 es.** are not us
d750: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 ed by the SQLite
d760: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 core. These op
d770: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 tional interface
d780: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a s are provided.*
d790: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 * by some VFSes
d7a0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 to facilitate te
d7b0: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 sting of the VFS
d7c0: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 code. By overri
d7d0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 ding .** system
d7e0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 calls with funct
d7f0: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 ions under its c
d800: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 ontrol, a test p
d810: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 rogram can.** si
d820: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e mulate faults an
d830: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f d error conditio
d840: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 ns that would ot
d850: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 herwise be diffi
d860: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 cult.** or impos
d870: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e sible to induce.
d880: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 The set of sys
d890: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 tem calls that c
d8a0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
d8b0: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 .** varies from
d8c0: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 one VFS to anoth
d8d0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 er, and from one
d8e0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 version of the
d8f0: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a same VFS to the.
d900: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 ** next. Applic
d910: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 ations that use
d920: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
d930: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 must be prepare
d940: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 d for any.** or
d950: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 all of these int
d960: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 erfaces to be NU
d970: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 LL or for their
d980: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e behavior to chan
d990: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 ge.** from one r
d9a0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 elease to the ne
d9b0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
d9c0: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d s must not attem
d9d0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 pt to access.**
d9e0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 any of these met
d9f0: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 hods if the iVer
da00: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 sion of the VFS
da10: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a is less than 3..
da20: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
da30: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 t sqlite3_vfs sq
da40: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 lite3_vfs;.typed
da50: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
da60: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 3_syscall_ptr)(v
da70: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c oid);.struct sql
da80: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 ite3_vfs {. int
da90: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 iVersion;
daa0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 /* Structu
dab0: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 re version numbe
dac0: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 r (currently 3)
dad0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c */. int szOsFil
dae0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a e; /*
daf0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 Size of subclas
db00: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 sed sqlite3_file
db10: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 */. int mxPath
db20: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f name; /
db30: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 * Maximum file p
db40: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a athname length *
db50: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 /. sqlite3_vfs
db60: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 *pNext; /*
db70: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 Next registered
db80: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 VFS */. const c
db90: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 har *zName;
dba0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 /* Name of thi
dbb0: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 s virtual file s
dbc0: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 ystem */. void
dbd0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
dbe0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 /* Pointer t
dbf0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 o application-sp
dc00: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 ecific data */.
dc10: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 int (*xOpen)(sq
dc20: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
dc30: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 t char *zName, s
dc40: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 qlite3_file*,.
dc50: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
dc60: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 flags, int *pOu
dc70: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 tFlags);. int (
dc80: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 *xDelete)(sqlite
dc90: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
dca0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 ar *zName, int s
dcb0: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 yncDir);. int (
dcc0: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 *xAccess)(sqlite
dcd0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
dce0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 ar *zName, int f
dcf0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f lags, int *pResO
dd00: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 ut);. int (*xFu
dd10: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 llPathname)(sqli
dd20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
dd30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
dd40: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 nOut, char *zOu
dd50: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 t);. void *(*xD
dd60: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 lOpen)(sqlite3_v
dd70: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
dd80: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 *zFilename);. v
dd90: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 oid (*xDlError)(
dda0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
ddb0: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
ddc0: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 ErrMsg);. void
ddd0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 (*(*xDlSym)(sqli
dde0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 te3_vfs*,void*,
ddf0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d const char *zSym
de00: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 bol))(void);. v
de10: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 oid (*xDlClose)(
de20: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f sqlite3_vfs*, vo
de30: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 id*);. int (*xR
de40: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 andomness)(sqlit
de50: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
de60: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b te, char *zOut);
de70: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 . int (*xSleep)
de80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
de90: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 nt microseconds)
dea0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 ;. int (*xCurre
deb0: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f ntTime)(sqlite3_
dec0: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a vfs*, double*);.
ded0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 int (*xGetLast
dee0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 Error)(sqlite3_v
def0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a fs*, int, char *
df00: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 );. /*. ** The
df10: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 methods above a
df20: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 re in version 1
df30: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
df40: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 s object. ** de
df50: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 finition. Those
df60: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 that follow are
df70: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f added in versio
df80: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a n 2 or later. *
df90: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 /. int (*xCurre
dfa0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c ntTimeInt64)(sql
dfb0: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 ite3_vfs*, sqlit
dfc0: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a e3_int64*);. /*
dfd0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
dfe0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
dff0: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 ersions 1 and 2
e000: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
e010: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 s object.. ** T
e020: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 hose below are f
e030: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 or version 3 and
e040: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 greater.. */.
e050: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 int (*xSetSyste
e060: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
e070: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
e080: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
e090: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 syscall_ptr);.
e0a0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
e0b0: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d ptr (*xGetSystem
e0c0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 Call)(sqlite3_vf
e0d0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
e0e0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 zName);. const
e0f0: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 char *(*xNextSys
e100: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
e110: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e120: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a r *zName);. /*.
e130: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 ** The methods
e140: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 above are in ve
e150: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 rsions 1 through
e160: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 3 of the sqlite
e170: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
e180: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 * New fields may
e190: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 be appended in
e1a0: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e figure versions.
e1b0: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 The iVersion.
e1c0: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 ** value will i
e1d0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 ncrement wheneve
e1e0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 r this happens.
e1f0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 . */.};../*.**
e200: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
e210: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 for the xAccess
e220: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
e230: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
e240: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
e250: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
e260: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
e270: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
e280: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
e290: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
e2a0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
e2b0: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
e2c0: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
e2d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
e2e0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
e2f0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
e300: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
e310: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
e320: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
e330: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
e340: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
e350: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
e360: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
e370: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
e380: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
e390: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 the named direc
e3a0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 tory is both rea
e3b0: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
e3c0: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 le.** (in other
e3d0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 words, if files
e3e0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 can be added, re
e3f0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d moved, and renam
e400: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 ed within.** the
e410: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 directory)..**
e420: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 The SQLITE_ACCES
e430: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 S_READWRITE cons
e440: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c tant is currentl
e450: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 y used only by t
e460: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 he.** [temp_stor
e470: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 e_directory prag
e480: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 ma], though this
e490: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e could change in
e4a0: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c a future.** rel
e4b0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
e4c0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
e4d0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 CCESS_READ, the
e4e0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
e4f0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
e500: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 the file is rea
e510: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 dable. The SQLI
e520: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 TE_ACCESS_READ c
e530: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 onstant is.** cu
e540: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 rrently unused,
e550: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 though it might
e560: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 be used in a fut
e570: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a ure release of.*
e580: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 * SQLite..*/.#de
e590: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
e5a0: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 SS_EXISTS 0.#
e5b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
e5c0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 CESS_READWRITE 1
e5d0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 /* Used by PR
e5e0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f AGMA temp_store_
e5f0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 directory */.#de
e600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
e610: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 SS_READ 2
e620: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f /* Unused */../
e630: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
e640: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 lags for the xSh
e650: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 mLock VFS method
e660: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
e670: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 eger constants d
e680: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 efine the variou
e690: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 s locking operat
e6a0: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 ions.** allowed
e6b0: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 by the xShmLock
e6c0: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 method of [sqlit
e6d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 e3_io_methods].
e6e0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e The.** followin
e6f0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c g are the only l
e700: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e egal combination
e710: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 s of flags to th
e720: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 e.** xShmLock me
e730: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
e740: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
e750: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
e760: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
e770: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
e780: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f M_LOCK | SQLITE_
e790: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a SHM_EXCLUSIVE.**
e7a0: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
e7b0: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
e7c0: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 E_SHM_SHARED.**
e7d0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
e7e0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 _UNLOCK | SQLITE
e7f0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
e800: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 * </ul>.**.** Wh
e810: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 en unlocking, th
e820: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 e same SHARED or
e830: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 EXCLUSIVE flag
e840: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 must be supplied
e850: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e as.** was given
e860: 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f no the correspo
e870: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a nding lock. .**
e880: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
e890: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e method can tran
e8a0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 sition between u
e8b0: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 nlocked and SHAR
e8c0: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e ED or.** between
e8d0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 unlocked and EX
e8e0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e CLUSIVE. It can
e8f0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 not transition b
e900: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a etween SHARED.**
e910: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a and EXCLUSIVE..
e920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
e930: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 E_SHM_UNLOCK
e940: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
e950: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 ITE_SHM_LOCK
e960: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
e970: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
e980: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
e990: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c SQLITE_SHM_EXCL
e9a0: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a USIVE 8../*.*
e9b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 * CAPI3REF: Maxi
e9c0: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 mum xShmLock ind
e9d0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 ex.**.** The xSh
e9e0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 mLock method on
e9f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
ea00: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c ods] may use val
ea10: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 ues.** between 0
ea20: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 and this upper
ea30: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 bound as its "of
ea40: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a fset" argument..
ea50: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
ea60: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 re will never at
ea70: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 tempt to acquire
ea80: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a or release a.**
ea90: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 lock outside of
eaa0: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 this range.*/.#
eab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
eac0: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 M_NLOCK 8
ead0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
eae0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 F: Initialize Th
eaf0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
eb00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
eb10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
eb20: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
eb30: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
eb40: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 te library. ^Th
eb50: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
eb60: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
eb70: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
eb80: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
eb90: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
eba0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
ebb0: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 ize()..** These
ebc0: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 routines are des
ebd0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 igned to aid in
ebe0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 process initiali
ebf0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 zation and.** sh
ec00: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 utdown on embedd
ec10: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 ed systems. Wor
ec20: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 kstation applica
ec30: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 tions using.** S
ec40: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 QLite normally d
ec50: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e o not need to in
ec60: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 voke either of t
ec70: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
ec80: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
ec90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
eca0: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 e() is an "effec
ecb0: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
ecc0: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 is.** the first
ecd0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e time sqlite3_in
ece0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
ecf0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 voked during the
ed00: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 lifetime of.**
ed10: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 the process, or
ed20: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
ed30: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
ed40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
ed50: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f invoked.** follo
ed60: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 wing a call to s
ed70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
ed80: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 ). ^(Only an ef
ed90: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 fective call.**
eda0: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 of sqlite3_initi
edb0: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 alize() does any
edc0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e initialization.
edd0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c All other call
ede0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 s.** are harmles
edf0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
ee00: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
ee10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
ee20: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
ee30: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 call if it is t
ee40: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c he first.** call
ee50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
ee60: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 down() since the
ee70: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e last sqlite3_in
ee80: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f itialize(). ^(O
ee90: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 nly.** an effect
eea0: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ive call to sqli
eeb0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 te3_shutdown() d
eec0: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 oes any deinitia
eed0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c lization..** All
eee0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c other valid cal
eef0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ls to sqlite3_sh
ef00: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 utdown() are har
ef10: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
ef20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
ef30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
ef40: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 nterface is thre
ef50: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 adsafe, but sqli
ef60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
ef70: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 * is not. The s
ef80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
ef90: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 ) interface must
efa0: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
efb0: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 from a.** single
efc0: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 thread. All op
efd0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
efe0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 nections] must b
eff0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c e closed and all
f000: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 .** other SQLite
f010: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 resources must
f020: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 be deallocated p
f030: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 rior to invoking
f040: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 .** sqlite3_shut
f050: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d down()..**.** Am
f060: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 ong other things
f070: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 , ^sqlite3_initi
f080: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 alize() will inv
f090: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f oke.** sqlite3_o
f0a0: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c s_init(). Simil
f0b0: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 arly, ^sqlite3_s
f0c0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c hutdown().** wil
f0d0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 l invoke sqlite3
f0e0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a _os_end()..**.**
f0f0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
f100: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
f110: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
f120: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
f130: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f s..** ^If for so
f140: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 me reason, sqlit
f150: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
f160: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 is unable to ini
f170: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c tialize.** the l
f180: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 ibrary (perhaps
f190: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
f1a0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 allocate a neede
f1b0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a d resource such.
f1c0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 ** as a mutex) i
f1d0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 t returns an [er
f1e0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 ror code] other
f1f0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d than [SQLITE_OK]
f200: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
f210: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f220: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
f230: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 led internally b
f240: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 y many other.**
f250: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
f260: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 s so that an app
f270: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 lication usually
f280: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
f290: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
f2a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f2b0: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 directly. For
f2c0: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 example, [sqlite
f2d0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 3_open()].** cal
f2e0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
f2f0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 alize() so the S
f300: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
f310: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
f320: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a lly.** initializ
f330: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
f340: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c _open()] is call
f350: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 ed if it has not
f360: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a be initialized.
f370: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f ** already. ^Ho
f380: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
f390: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
f3a0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d h the [SQLITE_OM
f3b0: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 IT_AUTOINIT].**
f3c0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
f3d0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 ion, then the au
f3e0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f tomatic calls to
f3f0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f400: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 ize().** are omi
f410: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 tted and the app
f420: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 lication must ca
f430: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ll sqlite3_initi
f440: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
f450: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 .** prior to usi
f460: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
f470: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
f480: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 For maximum port
f490: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 ability,.** it i
f4a0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
f4b0: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 at applications
f4c0: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 always invoke sq
f4d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f4e0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 ().** directly p
f4f0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
f500: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
f510: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 nterface. Futur
f520: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 e releases.** of
f530: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 SQLite may requ
f540: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 ire this. In ot
f550: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 her words, the b
f560: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 ehavior exhibite
f570: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 d.** when SQLite
f580: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
f590: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 h [SQLITE_OMIT_A
f5a0: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 UTOINIT] might b
f5b0: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 ecome the.** def
f5c0: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e ault behavior in
f5d0: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c some future rel
f5e0: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
f5f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
f600: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 3_os_init() rout
f610: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 ine does operati
f620: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
f630: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 ic.** initializa
f640: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
f650: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
f660: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
f670: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 ).** routine und
f680: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
f690: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
f6a0: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 t(). Typical ta
f6b0: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 sks.** performed
f6c0: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e by these routin
f6d0: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 es include alloc
f6e0: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 ation or dealloc
f6f0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 ation.** of stat
f700: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e ic resources, in
f710: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 itialization of
f720: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 global variables
f730: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 ,.** setting up
f740: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 a default [sqlit
f750: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 e3_vfs] module,
f760: 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a or setting up.**
f770: 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 a default confi
f780: 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b guration using [
f790: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
f7a0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 ]..**.** The app
f7b0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
f7c0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 never invoke eit
f7d0: 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 her sqlite3_os_i
f7e0: 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 nit().** or sqli
f7f0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 te3_os_end() dir
f800: 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c ectly. The appl
f810: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f ication should o
f820: 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 nly invoke.** sq
f830: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f840: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 () and sqlite3_s
f850: 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 hutdown(). The
f860: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
f870: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
f880: 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 s called automat
f890: 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
f8a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
f8b0: 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 nd.** sqlite3_os
f8c0: 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 _end() is called
f8d0: 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 by sqlite3_shut
f8e0: 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 down(). Appropr
f8f0: 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e iate.** implemen
f900: 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 tations for sqli
f910: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
f920: 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
f930: 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 ().** are built
f940: 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e into SQLite when
f950: 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 it is compiled
f960: 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 for Unix, Window
f970: 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 s, or OS/2..** W
f980: 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c hen [custom buil
f990: 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f ds | built for o
f9a0: 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a ther platforms].
f9b0: 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 ** (using the [S
f9c0: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 QLITE_OS_OTHER=1
f9d0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
f9e0: 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 * option) the ap
f9f0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 plication must s
fa00: 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 upply a suitable
fa10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
fa20: 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
fa30: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
fa40: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 ite3_os_end().
fa50: 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 An application-s
fa60: 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 upplied.** imple
fa70: 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
fa80: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f ite3_os_init() o
fa90: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
faa0: 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 ().** must retur
fab0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
fac0: 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d success and som
fad0: 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 e other [error c
fae0: 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 ode] upon.** fai
faf0: 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f lure..*/.SQLITE_
fb00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
fb10: 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 initialize(void)
fb20: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
fb30: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
fb40: 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f n(void);.SQLITE_
fb50: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
fb60: 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 os_init(void);.S
fb70: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
fb80: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
fb90: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
fba0: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
fbb0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
fbc0: 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ary.**.** The sq
fbd0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
fbe0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
fbf0: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
fc00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
fc10: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
fc20: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
fc30: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
fc40: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
fc50: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
fc60: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
fc70: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
fc80: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
fc90: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
fca0: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
fcb0: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
fcc0: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
fcd0: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
fce0: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
fcf0: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
fd00: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
fd10: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
fd20: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 ** The sqlite3_c
fd30: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
fd40: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 e is not threads
fd50: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 afe. The applic
fd60: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e ation.** must in
fd70: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 sure that no oth
fd80: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
fd90: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 aces are invoked
fda0: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 by other.** thr
fdb0: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 eads while sqlit
fdc0: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 e3_config() is r
fdd0: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 unning. Further
fde0: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f more, sqlite3_co
fdf0: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e nfig().** may on
fe00: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
fe10: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
fe20: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
fe30: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
fe40: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
fe50: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
fe60: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
fe70: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
fe80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
fe90: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
fea0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
feb0: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
fec0: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
fed0: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
fee0: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
fef0: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
ff00: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
ff10: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
ff20: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
ff30: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
ff40: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
ff50: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
ff60: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
ff70: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
ff80: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
ff90: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
ffa0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
ffb0: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
ffc0: 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f ** [configuratio
ffd0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 n option] that d
ffe0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 etermines.** wha
fff0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 t property of SQ
10000 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f Lite is to be co
10010 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 nfigured. Subse
10020 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a quent arguments.
10030 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ** vary dependin
10040 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 g on the [config
10050 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a uration option].
10060 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
10070 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
10080 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 ^When a configur
10090 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
100a0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
100b0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
100c0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 QLITE_OK]..** ^I
100d0 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 f the option is
100e0 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 unknown or SQLit
100f0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 e is unable to s
10100 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a et the option.**
10110 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
10120 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ne returns a non
10130 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
10140 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 e]..*/.SQLITE_AP
10150 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
10160 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a nfig(int, ...);.
10170 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10180 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 Configure datab
10190 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a ase connections.
101a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
101b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 3_db_config() in
101c0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
101d0 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 to make configur
101e0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 ation.** changes
101f0 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 to a [database
10200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 connection]. Th
10210 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 e interface is s
10220 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 imilar to.** [sq
10230 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
10240 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 except that the
10250 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f changes apply to
10260 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 a single.** [da
10270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
10280 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e n] (specified in
10290 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
102a0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ent)..**.** The
102b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
102c0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
102d0 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 nfig(D,V,...) i
102e0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
102f0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
10300 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 IDE | configurat
10310 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 ion verb] - an i
10320 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 nteger code .**
10330 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 that indicates w
10340 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 hat aspect of th
10350 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
10360 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 ection] is being
10370 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 configured..**
10380 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d Subsequent argum
10390 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 ents vary depend
103a0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 ing on the confi
103b0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a guration verb..*
103c0 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 *.** ^Calls to s
103d0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
103e0 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 () return SQLITE
103f0 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 _OK if and only
10400 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 if.** the call i
10410 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 s considered suc
10420 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 cessful..*/.SQLI
10430 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
10440 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c e3_db_config(sql
10450 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e ite3*, int op, .
10460 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
10470 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
10480 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ocation Routines
10490 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
104a0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
104b0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
104c0 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
104d0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
104e0 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
104f0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
10500 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
10510 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
10520 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
10530 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
10540 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
10550 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
10560 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
10570 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
10580 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
10590 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
105a0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
105b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
105c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
105d0 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 MALLOC] or [SQLI
105e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
105f0 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 LOC]. .** By cr
10600 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e eating an instan
10610 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
10620 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 t.** and passing
10630 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
10640 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
10650 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a CONFIG_MALLOC]).
10660 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 ** during config
10670 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c uration, an appl
10680 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 ication can spec
10690 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
106a0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
106b0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
106c0 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 m for SQLite to
106d0 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
106e0 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 ts.** dynamic me
106f0 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a mory needs..**.*
10700 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 * Note that SQLi
10710 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 te comes with se
10720 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 veral [built-in
10730 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
10740 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 s].** that are p
10750 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 erfectly adequat
10760 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 e for the overwh
10770 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 elming majority
10780 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
10790 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 ** and that this
107a0 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 object is only
107b0 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 useful to a tiny
107c0 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 minority of app
107d0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 lications.** wit
107e0 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 h specialized me
107f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
10800 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 requirements. T
10810 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a his object is.**
10820 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e also used durin
10830 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c g testing of SQL
10840 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
10850 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
10860 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
10870 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 allocator that
10880 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 simulates memory
10890 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 out-of-memory c
108a0 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 onditions in.**
108b0 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 order to verify
108c0 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f that SQLite reco
108d0 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 vers gracefully
108e0 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e from such.** con
108f0 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 ditions..**.** T
10900 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 he xMalloc, xRea
10910 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 lloc, and xFree
10920 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 methods must wor
10930 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 k like the.** ma
10940 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 lloc(), realloc(
10950 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e ) and free() fun
10960 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
10970 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
10980 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 ry..** ^SQLite g
10990 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
109a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
109b0 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f nt to.** xReallo
109c0 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 c is always a va
109d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
109e0 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 a prior call to
109f0 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 xRoundup..**.**
10a00 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 xSize should ret
10a10 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 urn the allocate
10a20 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f d size of a memo
10a30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
10a40 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
10a50 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f ined from xMallo
10a60 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 c or xRealloc.
10a70 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 The allocated si
10a80 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ze.** is always
10a90 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 at least as big
10aa0 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 as the requested
10ab0 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 size but may be
10ac0 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 larger..**.** T
10ad0 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 he xRoundup meth
10ae0 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 od returns what
10af0 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c would be the all
10b00 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a ocated size of.*
10b10 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 * a memory alloc
10b20 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 ation given a pa
10b30 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 rticular request
10b40 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d ed size. Most m
10b50 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
10b60 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d ors round up mem
10b70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
10b80 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 at least to the
10b90 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a next multiple.**
10ba0 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c of 8. Some all
10bb0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
10bc0 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c to a larger mul
10bd0 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f tiple or to a po
10be0 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 wer of 2..** Eve
10bf0 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ry memory alloca
10c00 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d tion request com
10c10 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b ing in through [
10c20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
10c30 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
10c40 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 _realloc()] firs
10c50 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 t calls xRoundup
10c60 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 . If xRoundup r
10c70 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 eturns 0, .** th
10c80 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f at causes the co
10c90 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f rresponding memo
10ca0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
10cb0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fail..**.** The
10cc0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e xInit method in
10cd0 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 itializes the me
10ce0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 mory allocator.
10cf0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a For example,.**
10d00 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
10d10 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
10d20 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
10d30 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
10d40 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
10d50 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
10d60 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
10d70 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
10d80 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
10d90 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
10da0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
10db0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
10dc0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
10dd0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
10de0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
10df0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
10e00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
10e10 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
10e20 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
10e30 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
10e40 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
10e50 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
10e60 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
10e70 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
10e80 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
10e90 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
10ea0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
10eb0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
10ec0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
10ed0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
10ee0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
10ef0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
10f00 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
10f10 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
10f20 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
10f30 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
10f40 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
10f50 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
10f60 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
10f70 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
10f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
10f90 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
10fa0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
10fb0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
10fc0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
10fd0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
10fe0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
10ff0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
11000 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
11010 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
11020 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
11030 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
11040 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
11050 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
11060 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
11070 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
11080 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
11090 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
110a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
110b0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
110c0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
110d0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
110e0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
110f0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
11100 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
11110 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
11120 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
11130 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
11140 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
11150 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
11160 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
11170 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
11180 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
11190 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
111a0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
111b0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
111c0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
111d0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
111e0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
111f0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
11200 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
11210 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
11220 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
11230 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
11240 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
11250 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
11260 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
11270 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
11280 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
11290 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
112a0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
112b0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
112c0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
112d0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
112e0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
112f0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
11300 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
11310 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
11320 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
11330 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
11340 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
11350 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
11360 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
11370 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
11380 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
11390 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
113a0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
113b0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b ion Options.** K
113c0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 EYWORDS: {config
113d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a uration option}.
113e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
113f0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
11400 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
11410 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
11420 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
11430 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
11440 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
11450 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
11460 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
11470 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
11480 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
11490 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
114a0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
114b0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
114c0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
114d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
114e0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
114f0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
11500 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
11510 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
11520 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
11530 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
11540 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
11550 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
11560 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
11570 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
11580 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
11590 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
115a0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
115b0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
115c0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
115d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
115e0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
115f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
11600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
11610 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
11620 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
11630 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
11640 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
11650 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
11660 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
11670 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
11680 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
11690 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
116a0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e o Single-thread.
116b0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
116c0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
116d0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
116e0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
116f0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
11700 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
11710 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
11720 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 le thread. ^If
11730 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
11740 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
11750 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
11760 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
11770 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
11780 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
11790 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
117a0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e possible to chan
117b0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ge the [threadin
117c0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 g mode] from its
117d0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 default.** valu
117e0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 e of Single-thre
117f0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 ad and so [sqlit
11800 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
11810 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 l return .** [SQ
11820 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
11830 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 alled with the S
11840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
11850 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e GLETHREAD.** con
11860 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11870 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
11880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
11890 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e LTITHREAD]] <dt>
118a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
118b0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
118c0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
118d0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
118e0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
118f0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
11900 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
11910 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 g mode] to Multi
11920 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
11930 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
11940 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e ables.** mutexin
11950 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 g on [database c
11960 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
11970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
11980 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
11990 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
119a0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
119b0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 or serializing a
119c0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 ccess to.** [dat
119d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
119e0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
119f0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 statements]. B
11a00 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 ut other mutexes
11a10 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
11a20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 so that SQLite w
11a30 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 ill be safe to u
11a40 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 se in a multi-th
11a50 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f readed.** enviro
11a60 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 nment as long as
11a70 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 no two threads
11a80 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
11a90 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 he same.** [data
11aa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
11ab0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
11ac0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 e. ^If SQLite i
11ad0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
11ae0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
11af0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
11b00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
11b10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
11b20 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
11b30 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
11b40 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 to set the Multi
11b50 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
11b60 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
11b70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
11b80 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
11b90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
11ba0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
11bb0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
11bc0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f G_MULTITHREAD co
11bd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
11be0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
11bf0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
11c00 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e ERIALIZED]] <dt>
11c10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
11c20 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a RIALIZED</dt>.**
11c30 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
11c40 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
11c50 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
11c60 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
11c70 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
11c80 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c mode] to Serial
11c90 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 ized. In other w
11ca0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f ords, this optio
11cb0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c n enables.** all
11cc0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 mutexes includi
11cd0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 ng the recursive
11ce0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b .** mutexes on [
11cf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
11d00 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
11d10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
11d20 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 jects..** In thi
11d30 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 s mode (which is
11d40 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 the default whe
11d50 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 n SQLite is comp
11d60 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 iled with.** [SQ
11d70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
11d80 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 1]) the SQLite l
11d90 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 ibrary will itse
11da0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 lf serialize acc
11db0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 ess.** to [datab
11dc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
11dd0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
11de0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 tatements] so th
11df0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 at the.** applic
11e00 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f ation is free to
11e10 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 use the same [d
11e20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
11e30 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 on] or the.** sa
11e40 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
11e50 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 tement] in diffe
11e60 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 rent threads at
11e70 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a the same time..*
11e80 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 * ^If SQLite is
11e90 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
11ea0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
11eb0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
11ec0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
11ed0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
11ee0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
11ef0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
11f00 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 set the Seriali
11f10 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
11f20 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
11f30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
11f40 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
11f50 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
11f60 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
11f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
11f80 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 RIALIZED configu
11f90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
11fa0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
11fb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
11fc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
11fd0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
11fe0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 .** <dd> ^(This
11ff0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
12000 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
12010 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 hich is a pointe
12020 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 r to an.** insta
12030 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
12040 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
12050 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 structure. The
12060 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
12070 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
12080 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d ve low-level mem
12090 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
120a0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
120b0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a ed in place of.*
120c0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c * the memory all
120d0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
120e0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
120f0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 te.)^ ^SQLite ma
12100 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 kes.** its own p
12110 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
12120 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
12130 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
12140 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
12150 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 e.** before the
12160 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12170 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e )] call returns.
12180 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
12190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
121a0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 ALLOC]] <dt>SQLI
121b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
121c0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
121d0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
121e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
121f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
12200 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a a pointer to an.
12210 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 ** instance of t
12220 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
12230 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
12240 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 re. The [sqlite
12250 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
12260 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
12270 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
12280 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
12290 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
122a0 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a on routines.)^.*
122b0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
122c0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
122d0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
122e0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
122f0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
12300 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
12310 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
12320 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
12330 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
12340 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
12350 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
12360 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
12370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
12380 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 MSTATUS]] <dt>SQ
12390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
123a0 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 TATUS</dt>.** <d
123b0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
123c0 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 takes single arg
123d0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
123e0 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 t, interpreted a
123f0 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c s a .** boolean,
12400 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f which enables o
12410 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 r disables the c
12420 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d ollection of mem
12430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a ory allocation .
12440 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e ** statistics. ^
12450 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c (When memory all
12460 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
12470 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c cs are disabled,
12480 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 the .** followi
12490 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ng SQLite interf
124a0 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d aces become non-
124b0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 operational:.**
124c0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e <ul>.** <li>
124d0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
124e0 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c _used()].** <l
124f0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f i> [sqlite3_memo
12500 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a ry_highwater()].
12510 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
12520 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d e3_soft_heap_lim
12530 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 it64()].** <li
12540 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 > [sqlite3_statu
12550 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 s()].** </ul>)
12560 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c ^.** ^Memory all
12570 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
12580 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 cs are enabled b
12590 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 y default unless
125a0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f SQLite is.** co
125b0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
125c0 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 ITE_DEFAULT_MEMS
125d0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 TATUS]=0 in whic
125e0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a h case memory.**
125f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
12600 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 istics are disab
12610 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a led by default..
12620 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b ** </dd>.**.** [
12630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
12640 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c CRATCH]] <dt>SQL
12650 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
12660 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 CH</dt>.** <dd>
12670 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 ^This option spe
12680 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 cifies a static
12690 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 memory buffer th
126a0 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
126b0 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 e for.** scratch
126c0 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 memory. There
126d0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
126e0 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 nts: A pointer
126f0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 an 8-byte.** ali
12700 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 gned memory buff
12710 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 er from which th
12720 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 e scratch alloca
12730 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a tions will be.**
12740 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 drawn, the size
12750 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 of each scratch
12760 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 allocation (sz)
12770 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 ,.** and the max
12780 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 imum number of s
12790 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f cratch allocatio
127a0 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a ns (N). The sz.
127b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 ** argument must
127c0 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f be a multiple o
127d0 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 f 16..** The fir
127e0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 st argument must
127f0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
12800 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e an 8-byte align
12810 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 ed buffer.** of
12820 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 at least sz*N by
12830 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a tes of memory..*
12840 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 * ^SQLite will u
12850 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 se no more than
12860 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 two scratch buff
12870 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 ers per thread.
12880 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 So.** N should
12890 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 be set to twice
128a0 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 the expected max
128b0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 imum number of t
128c0 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 hreads..** ^SQLi
128d0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 te will never re
128e0 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 quire a scratch
128f0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d buffer that is m
12900 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 ore than 6.** ti
12910 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 mes the database
12920 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 page size. ^If
12930 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 SQLite needs nee
12940 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a ds additional.**
12950 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 scratch memory
12960 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 beyond what is p
12970 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 rovided by this
12980 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
12990 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b tion, then .** [
129a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
129b0 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 ] will be used t
129c0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d o obtain the mem
129d0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e ory needed.</dd>
129e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
129f0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
12a00 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
12a10 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f NFIG_PAGECACHE</
12a20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
12a30 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 s option specifi
12a40 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
12a50 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 ry buffer that S
12a60 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f QLite can use fo
12a70 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 r.** the databas
12a80 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 e page cache wit
12a90 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 h the default pa
12aa0 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
12ab0 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 ntation. .** Th
12ac0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e is configuration
12ad0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 should not be u
12ae0 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 sed if an applic
12af0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 ation-define pag
12b00 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 e.** cache imple
12b10 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 mentation is loa
12b20 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 ded using the SQ
12b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
12b40 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 HE2 option..** T
12b50 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 here are three a
12b60 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 rguments to this
12b70 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 option: A point
12b80 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 er to 8-byte ali
12b90 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 gned.** memory,
12ba0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
12bb0 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a page buffer (sz
12bc0 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 ), and the numbe
12bd0 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a r of pages (N)..
12be0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 ** The sz argume
12bf0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 nt should be the
12c00 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 size of the lar
12c10 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 gest database pa
12c20 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f ge.** (a power o
12c30 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 f two between 51
12c40 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 2 and 32768) plu
12c50 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 s a little extra
12c60 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 for each.** pag
12c70 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 e header. ^The
12c80 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 page header size
12c90 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 is 20 to 40 byt
12ca0 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a es depending on.
12cb0 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 ** the host arch
12cc0 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 itecture. ^It i
12cd0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 s harmless, apar
12ce0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 t from the waste
12cf0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 d memory,.** to
12d00 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 make sz a little
12d10 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 too large. The
12d20 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 first.** argume
12d30 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 nt should point
12d40 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e to an allocation
12d50 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a of at least sz*
12d60 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 N bytes of memor
12d70 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 y..** ^SQLite wi
12d80 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 ll use the memor
12d90 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 y provided by th
12da0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
12db0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a to satisfy its.
12dc0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 ** memory needs
12dd0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 for the first N
12de0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 pages that it ad
12df0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 ds to cache. ^I
12e00 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
12e10 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
12e20 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
12e30 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
12e40 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 ded by this opti
12e50 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 on, then.** SQLi
12e60 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 te goes to [sqli
12e70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f te3_malloc()] fo
12e80 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c r the additional
12e90 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a storage space..
12ea0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 ** The pointer i
12eb0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
12ec0 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 ment must.** be
12ed0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d aligned to an 8-
12ee0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 byte boundary or
12ef0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
12f00 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a vior of SQLite.*
12f10 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 * will be undefi
12f20 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ned.</dd>.**.**
12f30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12f40 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 HEAP]] <dt>SQLIT
12f50 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 E_CONFIG_HEAP</d
12f60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
12f70 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
12f80 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
12f90 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
12fa0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a Lite will use.**
12fb0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
12fc0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 dynamic memory a
12fd0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 llocation needs
12fe0 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f beyond those pro
12ff0 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 vided.** for by
13000 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
13010 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c CRATCH] and [SQL
13020 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
13030 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 ACHE]..** There
13040 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
13050 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 nts: An 8-byte a
13060 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 ligned pointer t
13070 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a o the memory,.**
13080 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
13090 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f ytes in the memo
130a0 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 ry buffer, and t
130b0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
130c0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e ation size..** ^
130d0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 If the first poi
130e0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 nter (the memory
130f0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c pointer) is NUL
13100 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 L, then SQLite r
13110 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 everts.** to usi
13120 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d ng its default m
13130 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 emory allocator
13140 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c (the system mall
13150 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 oc() implementat
13160 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 ion),.** undoing
13170 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 any prior invoc
13180 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 ation of [SQLITE
13190 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e _CONFIG_MALLOC].
131a0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d ^If the.** mem
131b0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e ory pointer is n
131c0 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 ot NULL and eith
131d0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c er [SQLITE_ENABL
131e0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a E_MEMSYS3] or.**
131f0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
13200 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 MEMSYS5] are def
13210 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 ined, then the a
13220 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 lternative memor
13230 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 y.** allocator i
13240 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e s engaged to han
13250 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 dle all of SQLit
13260 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 es memory alloca
13270 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 tion needs..** T
13280 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 he first pointer
13290 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 (the memory poi
132a0 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c nter) must be al
132b0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
132c0 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f te.** boundary o
132d0 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 r subsequent beh
132e0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 avior of SQLite
132f0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 will be undefine
13300 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 d..** The minimu
13310 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
13320 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 e is capped at 2
13330 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 **12. Reasonable
13340 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 values.** for t
13350 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
13360 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 ation size are 2
13370 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 **5 through 2**8
13380 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
13390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
133a0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f EX]] <dt>SQLITE_
133b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 CONFIG_MUTEX</dt
133c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
133d0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
133e0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
133f0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
13400 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
13410 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
13420 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13430 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
13440 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
13450 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e cifies.** altern
13460 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 ative low-level
13470 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 mutex routines t
13480 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
13490 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 ce.** the mutex
134a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 routines built i
134b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e nto SQLite.)^ ^
134c0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
134d0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f opy of the.** co
134e0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
134f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
13500 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 ods] structure b
13510 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 efore the call t
13520 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
13530 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e nfig()] returns.
13540 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
13550 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
13560 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
13570 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
13580 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
13590 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
135a0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e n then.** the en
135b0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 tire mutexing su
135c0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 bsystem is omitt
135d0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c ed from the buil
135e0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c d and hence call
135f0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 s to.** [sqlite3
13600 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 _config()] with
13610 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 the SQLITE_CONFI
13620 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 G_MUTEX configur
13630 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c ation option wil
13640 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c l.** return [SQL
13650 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e ITE_ERROR].</dd>
13660 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
13670 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d CONFIG_GETMUTEX]
13680 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
13690 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 FIG_GETMUTEX</dt
136a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 >.** <dd> ^(This
136b0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
136c0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
136d0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 which is a point
136e0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 er to an.** inst
136f0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
13700 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13710 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
13720 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
13730 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a mutex_methods].*
13740 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
13750 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
13760 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
13770 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e mutex routines.
13780 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
13790 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
137a0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
137b0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f fault mutex allo
137c0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
137d0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
137e0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 r used to track
137f0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 mutex usage for
13800 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 performance.** p
13810 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 rofiling or test
13820 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 ing, for example
13830 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 . ^If SQLite i
13840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
13850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
13860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
13870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
13880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
13890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 tion then.** the
138a0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 entire mutexing
138b0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d subsystem is om
138c0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 itted from the b
138d0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 uild and hence c
138e0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
138f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
13900 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
13910 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f NFIG_GETMUTEX co
13920 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13930 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 on will.** retur
13940 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
13950 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
13960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
13970 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c KASIDE]] <dt>SQL
13980 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
13990 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 SIDE</dt>.** <dd
139a0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 > ^(This option
139b0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
139c0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 nts that determi
139d0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a ne the default.*
139e0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
139f0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b ion for the look
13a00 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c aside memory all
13a10 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a ocator on each.*
13a20 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
13a30 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 ection]. The fi
13a40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
13a50 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
13a60 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
13a70 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 ffer slot and th
13a80 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 e second is the
13a90 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f number of.** slo
13aa0 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 ts allocated to
13ab0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f each database co
13ac0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 nnection.)^ ^(T
13ad0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
13ae0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c the.** <i>defaul
13af0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 t</i> lookaside
13b00 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 size. The [SQLIT
13b10 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
13b20 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f SIDE].** verb to
13b30 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
13b40 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 fig()] can be us
13b50 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 ed to change the
13b60 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f lookaside.** co
13b70 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 nfiguration on i
13b80 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 ndividual connec
13b90 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a tions.)^ </dd>.*
13ba0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
13bb0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c NFIG_PCACHE2]] <
13bc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13bd0 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a _PCACHE2</dt>.**
13be0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 <dd> ^(This opt
13bf0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
13c00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
13c10 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 h is a pointer t
13c20 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 o.** an [sqlite3
13c30 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
13c40 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 ] object. This
13c50 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 object specifies
13c60 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a the interface.*
13c70 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 * to a custom pa
13c80 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
13c90 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c ntation.)^ ^SQL
13ca0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
13cb0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 of the.** objec
13cc0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f t and uses it fo
13cd0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d r page cache mem
13ce0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
13cf0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
13d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
13d10 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c CACHE2]] <dt>SQL
13d20 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
13d30 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHE2</dt>.** <d
13d40 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e d> ^(This option
13d50 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
13d60 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
13d70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
13d80 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 n.** [sqlite3_pc
13d90 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
13da0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
13db0 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 opies of the cur
13dc0 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 rent.** page cac
13dd0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
13de0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
13df0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a ct.)^ </dd>.**.*
13e00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13e10 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 G_LOG]] <dt>SQLI
13e20 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 TE_CONFIG_LOG</d
13e30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 t>.** <dd> The S
13e40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
13e50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
13e60 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 to configure the
13e70 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 SQLite.** globa
13e80 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a l [error log]..*
13e90 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 * (^The SQLITE_C
13ea0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e ONFIG_LOG option
13eb0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
13ec0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 ents: a pointer
13ed0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e to a.** function
13ee0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 with a call sig
13ef0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a nature of void(*
13f00 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
13f10 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e t char*), .** an
13f20 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 d a pointer to v
13f30 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e oid. ^If the fun
13f40 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 ction pointer is
13f50 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 not NULL, it is
13f60 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b .** invoked by [
13f70 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 sqlite3_log()] t
13f80 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c o process each l
13f90 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e ogging event. ^
13fa0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 If the.** functi
13fb0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 on pointer is NU
13fc0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 LL, the [sqlite3
13fd0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 _log()] interfac
13fe0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f e becomes a no-o
13ff0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 p..** ^The void
14000 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
14010 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
14020 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f ent to SQLITE_CO
14030 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 NFIG_LOG is.** p
14040 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
14050 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
14060 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c eter to the appl
14070 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
14080 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 logger.** functi
14090 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 on whenever that
140a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 function is inv
140b0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f oked. ^The seco
140c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a nd parameter to.
140d0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 ** the logger fu
140e0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 nction is a copy
140f0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 of the first pa
14100 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
14110 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
14120 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
14130 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 call and is inte
14140 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 nded to be a [re
14150 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e sult code] or an
14160 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
14170 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 sult code]. ^Th
14180 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
14190 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 r passed to the
141a0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 logger is.** log
141b0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 message after f
141c0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 ormatting via [s
141d0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
141e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 )]..** The SQLit
141f0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 e logging interf
14200 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 ace is not reent
14210 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 rant; the logger
14220 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 function.** sup
14230 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 plied by the app
14240 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
14250 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c t invoke any SQL
14260 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
14270 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 * In a multi-thr
14280 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
14290 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n, the applicati
142a0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
142b0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 r.** function mu
142c0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
142d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
142e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
142f0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 I]] <dt>SQLITE_C
14300 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 ONFIG_URI.** <dd
14310 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 >^(This option t
14320 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
14330 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 gument of type i
14340 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c nt. If non-zero,
14350 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e then.** URI han
14360 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
14370 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 y enabled. If th
14380 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a e parameter is z
14390 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 ero, then URI ha
143a0 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f ndling.** is glo
143b0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 bally disabled.)
143c0 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 ^ ^If URI handli
143d0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 ng is globally e
143e0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 nabled, all file
143f0 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 names.** passed
14400 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
14410 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
14420 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 en_v2()], [sqlit
14430 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a e3_open16()] or.
14440 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ** specified as
14450 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d part of [ATTACH]
14460 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e commands are in
14470 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 terpreted as URI
14480 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a s, regardless.**
14490 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
144a0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ot the [SQLITE_O
144b0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
144c0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 set when the da
144d0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
144e0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 tion is opened.
144f0 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c ^If it is global
14500 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c ly disabled, fil
14510 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e enames are.** on
14520 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 ly interpreted a
14530 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 s URIs if the SQ
14540 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c LITE_OPEN_URI fl
14550 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 ag is set when t
14560 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
14570 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 onnection is ope
14580 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c ned. ^(By defaul
14590 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 t, URI handling
145a0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 is globally.** d
145b0 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 isabled. The def
145c0 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 ault value may b
145d0 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d e changed by com
145e0 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a piling with the.
145f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 ** [SQLITE_USE_U
14600 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e RI] symbol defin
14610 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ed.)^.**.** [[SQ
14620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
14630 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
14640 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14650 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
14660 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e EX_SCAN.** <dd>^
14670 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
14680 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 s a single integ
14690 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 er argument whic
146a0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
146b0 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e as.** a boolean
146c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 in order to ena
146d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
146e0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 he use of coveri
146f0 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a ng indices for.*
14700 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 * full table sca
14710 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 ns in the query
14720 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 optimizer. ^The
14730 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 default setting
14740 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a is determined.*
14750 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 * by the [SQLITE
14760 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f _ALLOW_COVERING_
14770 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 INDEX_SCAN] comp
14780 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c ile-time option,
14790 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 or is "on".** i
147a0 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 f that compile-t
147b0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d ime option is om
147c0 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 itted..** The ab
147d0 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 ility to disable
147e0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 the use of cove
147f0 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 ring indices for
14800 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e full table scan
14810 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 s.** is because
14820 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 some incorrectly
14830 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 coded legacy ap
14840 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 plications might
14850 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 malfunction.**
14860 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a when the optimiz
14870 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
14880 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 . Providing the
14890 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 ability to.** d
148a0 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d isable the optim
148b0 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 ization allows t
148c0 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 he older, buggy
148d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 application code
148e0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 to work.** with
148f0 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 out change even
14900 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 with newer versi
14910 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a ons of SQLite..*
14920 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
14930 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b NFIG_PCACHE]] [[
14940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
14950 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 TPCACHE]].** <dt
14960 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 >SQLITE_CONFIG_P
14970 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 CACHE and SQLITE
14980 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
14990 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 E.** <dd> These
149a0 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f options are obso
149b0 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 lete and should
149c0 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e not be used by n
149d0 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 ew code..** They
149e0 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f are retained fo
149f0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 r backwards comp
14a00 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 atibility but ar
14a10 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a e now no-ops..**
14a20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
14a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
14a40 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c LOG]].** <dt>SQL
14a50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
14a60 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 G.** <dd>This op
14a70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 tion is only ava
14a80 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 ilable if sqlite
14a90 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
14aa0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
14ab0 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 _ENABLE_SQLLOG]
14ac0 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 pre-processor ma
14ad0 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 cro defined. The
14ae0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
14af0 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 should.** be a p
14b00 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 ointer to a func
14b10 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 tion of type voi
14b20 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 d(*)(void*,sqlit
14b30 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c e3*,const char*,
14b40 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 int)..** The se
14b50 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f cond should be o
14b60 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 f type (void*).
14b70 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 The callback is
14b80 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c invoked by the l
14b90 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 ibrary.** in thr
14ba0 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 ee separate circ
14bb0 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 umstances, ident
14bc0 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c ified by the val
14bd0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ue passed as the
14be0 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d .** fourth param
14bf0 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 eter. If the fou
14c00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
14c10 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 0, then the dat
14c20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14c30 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 .** passed as th
14c40 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
14c50 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 t has just been
14c60 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 opened. The thir
14c70 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f d argument.** po
14c80 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 ints to a buffer
14c90 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
14ca0 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e name of the main
14cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 database file.
14cc0 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 If the.** fourth
14cd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c parameter is 1,
14ce0 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 then the SQL st
14cf0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 atement that the
14d00 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
14d10 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 .** points to ha
14d20 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 s just been exec
14d30 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 uted. Or, if the
14d40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
14d50 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 r is 2, then.**
14d60 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 the connection b
14d70 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 eing passed as t
14d80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
14d90 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f ter is being clo
14da0 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 sed. The.** thir
14db0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 d parameter is p
14dc0 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 assed NULL In th
14dd0 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 is case. An exa
14de0 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 mple of using th
14df0 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 is.** configurat
14e00 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 ion option can b
14e10 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 e seen in the "t
14e20 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f est_sqllog.c" so
14e30 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 urce file in.**
14e40 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 the canonical SQ
14e50 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 Lite source tree
14e60 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
14e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
14e80 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e P_SIZE]].** <dt>
14e90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
14ea0 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e AP_SIZE.** <dd>^
14eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
14ec0 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 AP_SIZE takes tw
14ed0 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 o 64-bit integer
14ee0 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 (sqlite3_int64)
14ef0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 values.** that
14f00 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 are the default
14f10 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 mmap size limit
14f20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 (the default set
14f30 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 ting for.** [PRA
14f40 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 GMA mmap_size])
14f50 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 and the maximum
14f60 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a allowed mmap siz
14f70 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 e limit..** ^The
14f80 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 default setting
14f90 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 can be overridd
14fa0 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 en by each datab
14fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 ase connection u
14fc0 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 sing.** either t
14fd0 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f he [PRAGMA mmap_
14fe0 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f size] command, o
14ff0 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a r by using the.*
15000 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
15010 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 MMAP_SIZE] file
15020 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 control. ^(The
15030 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 maximum allowed
15040 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e mmap size.** can
15050 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 61 not be changed a
15060 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 t run-time. Nor
15070 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75 6d may the maximum
15080 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
15090 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68 65 ze.** exceed the
150a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 compile-time ma
150b0 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 ximum mmap size
150c0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 set by the.** [S
150d0 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 QLITE_MAX_MMAP_S
150e0 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d IZE] compile-tim
150f0 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e e option.)^.** ^
15100 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 If either argume
15110 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f nt to this optio
15120 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 n is negative, t
15130 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e hen that argumen
15140 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 t is.** changed
15150 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 to its compile-t
15160 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a ime default..**.
15170 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15180 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
15190 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 E]].** <dt>SQLIT
151a0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
151b0 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e EAPSIZE.** <dd>^
151c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f This option is o
151d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
151e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
151f0 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a led for Windows.
15200 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c ** with the [SQL
15210 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 ITE_WIN32_MALLOC
15220 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 ] pre-processor
15230 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a macro defined..*
15240 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
15250 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 WIN32_HEAPSIZE t
15260 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e akes a 32-bit un
15270 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 signed integer v
15280 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 alue.** that spe
15290 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d cifies the maxim
152a0 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 um size of the c
152b0 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 reated heap..**
152c0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
152d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
152e0 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
152f0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
15300 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15310 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
15320 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
15330 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
15340 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
15350 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
15360 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
15370 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
15380 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
15390 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
153a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
153b0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
153c0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
153d0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
153e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
153f0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
15400 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 6 /* void*,
15410 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
15420 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15430 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
15440 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 E 7 /* void
15450 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
15460 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15470 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 TE_CONFIG_HEAP
15480 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 8 /* vo
15490 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 id*, int nByte,
154a0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 int min */.#defi
154b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
154c0 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 _MEMSTATUS 9
154d0 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
154e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
154f0 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 ONFIG_MUTEX
15500 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 10 /* sqlite
15510 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
15520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15530 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
15540 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 EX 11 /* sq
15550 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
15560 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 ods* */./* previ
15570 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e ously SQLITE_CON
15580 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 FIG_CHUNKALLOC 1
15590 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 2 which is now u
155a0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 nused. */ .#defi
155b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
155c0 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 _LOOKASIDE 13
155d0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a /* int int */.
155e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
155f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 ONFIG_PCACHE
15600 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 14 /* no-op
15610 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
15620 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
15630 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d HE 15 /* no-
15640 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
15650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
15660 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 16 /*
15670 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a xFunc, void* */.
15680 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15690 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 ONFIG_URI
156a0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 17 /* int */
156b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
156c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 CONFIG_PCACHE2
156d0 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 18 /* sqlit
156e0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
156f0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
15700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
15710 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a PCACHE2 19 /*
15720 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
15730 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
15740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
15750 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
15760 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e X_SCAN 20 /* in
15770 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
15780 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
15790 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 G 21 /* x
157a0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f Sqllog, void* */
157b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
157c0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
157d0 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 22 /* sqlit
157e0 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 e3_int64, sqlite
157f0 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 3_int64 */.#defi
15800 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
15810 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
15820 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 23 /* int
15830 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nByte */../*.**
15840 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
15850 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f se Connection Co
15860 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 nfiguration Opti
15870 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
15880 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
15890 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
158a0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
158b0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
158c0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
158d0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 as the second ar
158e0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 gument to the [s
158f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
15900 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
15910 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
15920 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
15930 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
15940 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
15950 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
15960 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
15970 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
15980 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
15990 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
159a0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
159b0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
159c0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 from [sqlite3_d
159d0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d b_config()] to m
159e0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
159f0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
15a00 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 . ^The [sqlite3
15a10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
15a20 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
15a30 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
15a40 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
15a50 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
15a60 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
15a70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
15a80 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
15a90 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
15aa0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
15ab0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
15ac0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
15ad0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
15ae0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c three additional
15af0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
15b00 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a determine the .*
15b10 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d * [lookaside mem
15b20 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 ory allocator] c
15b30 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 onfiguration for
15b40 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
15b50 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e onnection]..** ^
15b60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
15b70 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 nt (the third pa
15b80 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
15b90 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
15ba0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 is a.** pointer
15bb0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 to a memory buf
15bc0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c fer to use for l
15bd0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e ookaside memory.
15be0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
15bf0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 rgument after th
15c00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
15c10 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 G_LOOKASIDE verb
15c20 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 .** may be NULL
15c30 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51 in which case SQ
15c40 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 Lite will alloca
15c50 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 te the.** lookas
15c60 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c ide buffer itsel
15c70 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 f using [sqlite3
15c80 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 _malloc()]. ^The
15c90 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
15ca0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 is the.** size
15cb0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 of each lookasid
15cc0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 e buffer slot.
15cd0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
15ce0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ent is the numbe
15cf0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 r of.** slots.
15d00 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
15d10 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 buffer in the fi
15d20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
15d30 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61 t be greater tha
15d40 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f n.** or equal to
15d50 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 the product of
15d60 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
15d70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 hird arguments.
15d80 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d The buffer.** m
15d90 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
15da0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e o an 8-byte boun
15db0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 dary. ^If the s
15dc0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
15dd0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f o.** SQLITE_DBCO
15de0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 NFIG_LOOKASIDE i
15df0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 s not a multiple
15e00 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 of 8, it is int
15e10 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 ernally.** round
15e20 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e ed down to the n
15e30 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 ext smaller mult
15e40 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 iple of 8. ^(Th
15e50 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
15e60 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 ry.** configurat
15e70 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 ion for a databa
15e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 se connection ca
15e90 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 n only be change
15ea0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 d when that.** c
15eb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 onnection is not
15ec0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 currently using
15ed0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
15ee0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 y, or in other w
15ef0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 ords.** when the
15f00 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 "current value"
15f10 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
15f20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 [sqlite3_db_stat
15f30 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f us](D,[SQLITE_CO
15f40 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c NFIG_LOOKASIDE],
15f50 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a ...) is zero..**
15f60 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
15f70 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 change the looka
15f80 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 side memory conf
15f90 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c iguration when l
15fa0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f ookaside.** memo
15fb0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 ry is in use lea
15fc0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 ves the configur
15fd0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 ation unchanged
15fe0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 and returns .**
15ff0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e [SQLITE_BUSY].)^
16000 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
16010 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
16020 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e ENABLE_FKEY</dt>
16030 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
16040 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f ption is used to
16050 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
16060 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 le the enforceme
16070 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 nt of.** [foreig
16080 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 n key constraint
16090 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c s]. There shoul
160a0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f d be two additio
160b0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a nal arguments..*
160c0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
160d0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 ment is an integ
160e0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f er which is 0 to
160f0 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f disable FK enfo
16100 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 rcement,.** posi
16110 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 tive to enable F
16120 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 K enforcement or
16130 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 negative to lea
16140 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e ve FK enforcemen
16150 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 t.** unchanged.
16160 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
16170 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
16180 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
16190 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 into which.** i
161a0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
161b0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
161c0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d ther FK enforcem
161d0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e ent is off or on
161e0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
161f0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
16200 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
16210 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
16220 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
16230 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e h case the FK en
16240 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e forcement settin
16250 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
16260 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a d back. </dd>.**
16270 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
16280 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 BCONFIG_ENABLE_T
16290 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c RIGGER</dt>.** <
162a0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
162b0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
162c0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 le or disable [C
162d0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 REATE TRIGGER |
162e0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 triggers]..** Th
162f0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 ere should be tw
16300 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 o additional arg
16310 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 uments..** The f
16320 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
16330 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
16340 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c h is 0 to disabl
16350 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 e triggers,.** p
16360 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
16370 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 e triggers or ne
16380 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 gative to leave
16390 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 the setting unch
163a0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 anged..** The se
163b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
163c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
163d0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
163e0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
163f0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
16400 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72 icate whether tr
16410 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62 iggers are disab
16420 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a led or enabled.*
16430 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 * following this
16440 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f call. The seco
16450 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 nd parameter may
16460 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
16470 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 er, in.** which
16480 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72 case the trigger
16490 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
164a0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
164b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e /dd>.**.** </dl>
164c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
164d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
164e0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31 ASIDE 1001
164f0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 /* void* int i
16500 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
16510 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
16520 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30 ABLE_FKEY 10
16530 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 02 /* int int*
16540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16550 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
16560 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20 E_TRIGGER 1003
16570 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
16580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
16590 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 : Enable Or Disa
165a0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 ble Extended Res
165b0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ult Codes.**.**
165c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 ^The sqlite3_ext
165d0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
165e0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 es() routine ena
165f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
16600 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the.** [extende
16610 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
16620 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 feature of SQLit
16630 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 e. ^The extended
16640 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 result.** codes
16650 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 are disabled by
16660 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 default for his
16670 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 torical compatib
16680 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ility..*/.SQLITE
16690 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
166a0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
166b0 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c _codes(sqlite3*,
166c0 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a int onoff);../*
166d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 .** CAPI3REF: La
166e0 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a st Insert Rowid.
166f0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 **.** ^Each entr
16700 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 y in most SQLite
16710 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 tables (except
16720 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 for [WITHOUT ROW
16730 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 ID] tables).** h
16740 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 as a unique 64-b
16750 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 it signed.** int
16760 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 eger key called
16770 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f the [ROWID | "ro
16780 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 wid"]. ^The rowi
16790 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 d is always avai
167a0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 lable.** as an u
167b0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e ndeclared column
167c0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 named ROWID, OI
167d0 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 D, or _ROWID_ as
167e0 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a long as those.*
167f0 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 * names are not
16800 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 also used by exp
16810 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 licitly declared
16820 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a columns. ^If.**
16830 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 the table has a
16840 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 column of type
16850 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 [INTEGER PRIMARY
16860 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 KEY] then that
16870 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f column.** is ano
16880 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 ther alias for t
16890 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 he rowid..**.**
168a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 ^The sqlite3_las
168b0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
168c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
168d0 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 rns the [rowid]
168e0 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 of the .** most
168f0 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 recent successfu
16900 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 l [INSERT] into
16910 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 a rowid table or
16920 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
16930 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 .** on database
16940 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a connection D..**
16950 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b ^Inserts into [
16960 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 WITHOUT ROWID] t
16970 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 ables are not re
16980 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e corded..** ^If n
16990 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e o successful [IN
169a0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 SERT]s into rowi
169b0 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 d tables.** have
169c0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f ever occurred o
169d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
169e0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a onnection D, .**
169f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 then sqlite3_la
16a00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
16a10 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e D) returns zero.
16a20 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b .**.** ^(If an [
16a30 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 INSERT] occurs w
16a40 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
16a50 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 or within a [vir
16a60 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d tual table].** m
16a70 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 ethod, then this
16a80 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 routine will re
16a90 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d turn the [rowid]
16aa0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 of the inserted
16ab0 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 .** row as long
16ac0 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f as the trigger o
16ad0 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 r virtual table
16ae0 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e method is runnin
16af0 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 g..** But once t
16b00 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 he trigger or vi
16b10 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 rtual table meth
16b20 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c od ends, the val
16b30 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 ue returned .**
16b40 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 by this routine
16b50 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 reverts to what
16b60 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 it was before th
16b70 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
16b80 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 tual.** table me
16b90 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a thod began.)^.**
16ba0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d .** ^An [INSERT]
16bb0 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
16bc0 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
16bd0 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
16be0 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
16bf0 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f [INSERT] and do
16c00 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
16c10 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
16c20 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
16c30 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 ine. ^Thus INSE
16c40 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 RT OR FAIL, INSE
16c50 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e RT OR IGNORE, IN
16c60 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b SERT OR ROLLBACK
16c70 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 ,.** and INSERT
16c80 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f OR ABORT make no
16c90 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
16ca0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
16cb0 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
16cc0 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 when their inser
16cd0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 tion fails. ^(W
16ce0 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 hen INSERT OR RE
16cf0 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 PLACE.** encount
16d00 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 ers a constraint
16d10 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 violation, it d
16d20 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 oes not fail. T
16d30 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e he.** INSERT con
16d40 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
16d50 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 tion after delet
16d60 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 ing rows that ca
16d70 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 used.** the cons
16d80 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 traint problem s
16d90 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c o INSERT OR REPL
16da0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ACE will always
16db0 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 change.** the re
16dc0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
16dd0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a is interface.)^.
16de0 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 **.** ^For the p
16df0 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
16e00 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 routine, an [INS
16e10 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 ERT] is consider
16e20 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
16e30 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
16e40 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
16e50 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
16e60 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
16e70 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 on is accessible
16e80 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e to SQL statemen
16e90 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c ts via the.** [l
16ea0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
16eb0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
16ec0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
16ed0 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 arate thread per
16ee0 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 forms a new [INS
16ef0 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 ERT] on the same
16f00 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
16f10 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
16f20 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
16f30 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
16f40 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ** function is r
16f50 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
16f60 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
16f70 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c insert [rowid],
16f80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c .** then the val
16f90 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ue returned by [
16fa0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
16fb0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a ert_rowid()] is.
16fc0 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 ** unpredictable
16fd0 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 and might not e
16fe0 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 qual either the
16ff0 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a old or the new.*
17000 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 * last insert [r
17010 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 owid]..*/.SQLITE
17020 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
17030 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 64 sqlite3_last_
17040 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c insert_rowid(sql
17050 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
17060 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 API3REF: Count T
17070 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 he Number Of Row
17080 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a s Modified.**.**
17090 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
170a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
170b0 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 er of database r
170c0 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 ows that were ch
170d0 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 anged.** or inse
170e0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 rted or deleted
170f0 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 by the most rece
17100 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 ntly completed S
17110 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL statement.**
17120 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 on the [database
17130 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 connection] spe
17140 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 cified by the fi
17150 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a rst parameter..*
17160 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 * ^(Only changes
17170 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 that are direct
17180 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ly specified by
17190 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 the [INSERT], [U
171a0 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 PDATE],.** or [D
171b0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 ELETE] statement
171c0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 are counted. A
171d0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 uxiliary changes
171e0 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 caused by.** tr
171f0 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 iggers or [forei
17200 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 gn key actions]
17210 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
17220 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 )^ Use the.** [s
17230 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
17240 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e nges()] function
17250 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 to find the tot
17260 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 al number of cha
17270 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e nges.** includin
17280 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 g changes caused
17290 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 by triggers and
172a0 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 foreign key act
172b0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 ions..**.** ^Cha
172c0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 nges to a view t
172d0 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 hat are simulate
172e0 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 d by an [INSTEAD
172f0 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 OF trigger].**
17300 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
17310 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c Only real tabl
17320 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f e changes are co
17330 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 unted..**.** ^(A
17340 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 "row change" is
17350 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 a change to a s
17360 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 ingle row of a s
17370 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 ingle table.** c
17380 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 aused by an INSE
17390 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 RT, DELETE, or U
173a0 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e PDATE statement.
173b0 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 Rows that.** a
173c0 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 re changed as si
173d0 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 de effects of [R
173e0 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 EPLACE] constrai
173f0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a nt resolution,.*
17400 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 * rollback, ABOR
17410 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 T processing, [D
17420 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 ROP TABLE], or b
17430 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d y any other.** m
17440 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 echanisms do not
17450 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 count as direct
17460 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a row changes.)^.
17470 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 **.** A "trigger
17480 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 context" is a s
17490 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f cope of executio
174a0 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e n that begins an
174b0 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 d.** ends with t
174c0 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b he script of a [
174d0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
174e0 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d trigger]. .** M
174f0 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ost SQL statemen
17500 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 ts are.** evalua
17510 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 ted outside of a
17520 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 ny trigger. Thi
17530 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 s is the "top le
17540 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 vel".** trigger
17550 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 context. If a t
17560 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f rigger fires fro
17570 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c m the top level,
17580 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 a.** new trigge
17590 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 r context is ent
175a0 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 ered for the dur
175b0 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e ation of that on
175c0 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 e.** trigger. S
175d0 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 ubtriggers creat
175e0 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f e subcontexts fo
175f0 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e r their duration
17600 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
17610 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 [sqlite3_exec()
17620 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 ] or [sqlite3_st
17630 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c ep()] recursivel
17640 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 y does.** not cr
17650 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 eate a new trigg
17660 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a er context..**.*
17670 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
17680 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
17690 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f ber of direct ro
176a0 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 w changes in the
176b0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 .** most recent
176c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 INSERT, UPDATE,
176d0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
176e0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 ent within the s
176f0 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 ame.** trigger c
17700 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ontext..**.** ^T
17710 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 hus, when called
17720 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 from the top le
17730 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 vel, this functi
17740 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a on returns the.*
17750 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e * number of chan
17760 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 ges in the most
17770 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 recent INSERT, U
17780 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 PDATE, or DELETE
17790 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 .** that also oc
177a0 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f curred at the to
177b0 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 p level. ^(With
177c0 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 in the body of a
177d0 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 trigger,.** the
177e0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
177f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e () interface can
17800 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 be called to fi
17810 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 nd the number of
17820 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 .** changes in t
17830 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
17840 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 completed INSER
17850 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 T, UPDATE, or DE
17860 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e LETE.** statemen
17870 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 t within the bod
17880 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 y of the same tr
17890 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 igger..** Howeve
178a0 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 r, the number re
178b0 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 turned does not
178c0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a include changes.
178d0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 ** caused by sub
178e0 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 triggers since t
178f0 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 hose have their
17900 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a own context.)^.*
17910 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 *.** See also th
17920 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c e [sqlite3_total
17930 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
17940 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 rface, the.** [c
17950 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 ount_changes pra
17960 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 gma], and the [c
17970 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
17980 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 ction]..**.** If
17990 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
179a0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 ad makes changes
179b0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 on the same dat
179c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
179d0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 .** while [sqlit
179e0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 e3_changes()] is
179f0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
17a00 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
17a10 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 .** is unpredict
17a20 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
17a30 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 ningful..*/.SQLI
17a40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
17a50 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 e3_changes(sqlit
17a60 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
17a70 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d I3REF: Total Num
17a80 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 ber Of Rows Modi
17a90 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 fied.**.** ^This
17aa0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
17ab0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
17ac0 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 row changes caus
17ad0 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a ed by [INSERT],.
17ae0 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b ** [UPDATE] or [
17af0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e DELETE] statemen
17b00 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 ts since the [da
17b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
17b20 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a n] was opened..*
17b30 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 * ^(The count re
17b40 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
17b50 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
17b60 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 ) includes all c
17b70 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 hanges.** from a
17b80 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 ll [CREATE TRIGG
17b90 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f ER | trigger] co
17ba0 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 ntexts and chang
17bb0 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 es made by.** [f
17bc0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
17bd0 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ns]. However,.**
17be0 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 the count does
17bf0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e not include chan
17c00 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c ges used to impl
17c10 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 ement [REPLACE]
17c20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 constraints,.**
17c30 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 do rollbacks or
17c40 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 ABORT processing
17c50 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 , or [DROP TABLE
17c60 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 ] processing. T
17c70 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 he.** count does
17c80 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 not include row
17c90 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 s of views that
17ca0 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 fire an [INSTEAD
17cb0 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a OF trigger],.**
17cc0 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 though if the I
17cd0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 NSTEAD OF trigge
17ce0 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 r makes changes
17cf0 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 of its own, thos
17d00 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 e changes .** ar
17d10 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 e counted.)^.**
17d20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 ^The sqlite3_tot
17d30 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e al_changes() fun
17d40 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 ction counts the
17d50 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e changes as soon
17d60 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 as.** the state
17d70 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 ment that makes
17d80 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 them is complete
17d90 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 d (when the stat
17da0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 ement handle.**
17db0 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 is passed to [sq
17dc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
17dd0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
17de0 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 ize()])..**.** S
17df0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c ee also the [sql
17e00 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
17e10 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a interface, the.*
17e20 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 * [count_changes
17e30 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 pragma], and th
17e40 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e [total_changes
17e50 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
17e60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
17e70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b arate thread mak
17e80 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 es changes on th
17e90 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
17ea0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 connection.** wh
17eb0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 ile [sqlite3_tot
17ec0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 al_changes()] is
17ed0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 running then th
17ee0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 e value.** retur
17ef0 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 ned is unpredict
17f00 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 able and not mea
17f10 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 ningful..*/.SQLI
17f20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
17f30 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 e3_total_changes
17f40 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
17f50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 ** CAPI3REF: Int
17f60 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 errupt A Long-Ru
17f70 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a nning Query.**.*
17f80 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
17f90 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
17fa0 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
17fb0 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
17fc0 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
17fd0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
17fe0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 portunity. This
17ff0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
18000 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
18010 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
18020 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
18030 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
18040 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
18050 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
18060 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
18070 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
18080 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
18090 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 ately..**.** ^It
180a0 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
180b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
180c0 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
180d0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
180e0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
180f0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
18100 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
18110 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
18120 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
18130 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
18140 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
18150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
18160 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
18170 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
18180 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
18190 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
181a0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
181b0 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 If an SQL operat
181c0 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 ion is very near
181d0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 ly finished at t
181e0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 he time when.**
181f0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
18200 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 t() is called, t
18210 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 hen it might not
18220 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 have an opportu
18230 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e nity.** to be in
18240 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 terrupted and mi
18250 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ght continue to
18260 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a completion..**.*
18270 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 * ^An SQL operat
18280 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
18290 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
182a0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
182b0 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 RRUPT]..** ^If t
182c0 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 he interrupted S
182d0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
182e0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
182f0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
18300 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
18310 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
18320 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 action, then the
18330 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 entire transact
18340 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 ion.** will be r
18350 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
18360 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 atically..**.**
18370 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
18380 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 errupt(D) call i
18390 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 s in effect unti
183a0 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 l all currently
183b0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 running.** SQL s
183c0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 tatements on [da
183d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
183e0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 n] D complete.
183f0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 ^Any new SQL sta
18400 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
18410 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
18420 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
18430 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 terrupt() call a
18440 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a nd before the .*
18450 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d * running statem
18460 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 ents reaches zer
18470 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 o are interrupte
18480 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 d as if they had
18490 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 been.** running
184a0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 prior to the sq
184b0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
184c0 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 ) call. ^New SQ
184d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
184e0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
184f0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 after the runni
18500 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 ng statement cou
18510 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 nt reaches zero
18520 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 are.** not effec
18530 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
18540 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a e3_interrupt()..
18550 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 ** ^A call to sq
18560 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
18570 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 D) that occurs w
18580 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f hen there are no
18590 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
185a0 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 statements is a
185b0 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f no-op and has no
185c0 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 effect on SQL s
185d0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
185e0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
185f0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
18600 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
18610 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
18620 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
18630 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
18640 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 s while [sqlite3
18650 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a _interrupt()].**
18660 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
18670 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c bad things will
18680 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a likely happen..
18690 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
186a0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 id sqlite3_inter
186b0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a rupt(sqlite3*);.
186c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
186d0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
186e0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 SQL Statement I
186f0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a s Complete.**.**
18700 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
18710 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e are useful durin
18720 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 g command-line i
18730 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e nput to determin
18740 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 e if the.** curr
18750 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 ently entered te
18760 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d xt seems to form
18770 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
18780 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 statement or.**
18790 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e if additional in
187a0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 put is needed be
187b0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 fore sending the
187c0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 text into.** SQ
187d0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 Lite for parsing
187e0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e . ^These routin
187f0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 es return 1 if t
18800 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a he input string.
18810 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 ** appears to be
18820 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
18830 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 statement. ^A s
18840 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 tatement is judg
18850 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ed to be.** comp
18860 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 lete if it ends
18870 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e with a semicolon
18880 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f token and is no
18890 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a t a prefix of a.
188a0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 ** well-formed C
188b0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 REATE TRIGGER st
188c0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 atement. ^Semic
188d0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 olons that are e
188e0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a mbedded within.*
188f0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c * string literal
18900 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e s or quoted iden
18910 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 tifier names or
18920 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 comments are not
18930 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 .** independent
18940 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 tokens (they are
18950 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b part of the tok
18960 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 en in which they
18970 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 are.** embedded
18980 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f ) and thus do no
18990 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 t count as a sta
189a0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f tement terminato
189b0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a r. ^Whitespace.
189c0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 ** and comments
189d0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 that follow the
189e0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 final semicolon
189f0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a are ignored..**.
18a00 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
18a10 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
18a20 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
18a30 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 incomplete. ^If
18a40 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
18a50 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 ocation fails, t
18a60 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d hen SQLITE_NOMEM
18a70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
18a80 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
18a90 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
18aa0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
18ab0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
18ac0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
18ad0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
18ae0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e ect SQL..**.** ^
18af0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e (If SQLite has n
18b00 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 ot been initiali
18b10 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 zed using [sqlit
18b20 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
18b30 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e prior .** to in
18b40 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 voking sqlite3_c
18b50 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e omplete16() then
18b60 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
18b70 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
18b80 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
18b90 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d y by sqlite3_com
18ba0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 plete16(). If t
18bb0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 hat initializati
18bc0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 on fails,.** the
18bd0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
18be0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
18bf0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c complete16() wil
18c00 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a l be non-zero.**
18c10 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
18c20 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
18c30 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 e input SQL is c
18c40 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a omplete.)^.**.**
18c50 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
18c60 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
18c70 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
18c80 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
18c90 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
18ca0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
18cb0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
18cc0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
18cd0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
18ce0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
18cf0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
18d00 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 e order..*/.SQLI
18d10 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
18d20 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 e3_complete(cons
18d30 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 t char *sql);.SQ
18d40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
18d50 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
18d60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
18d70 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
18d80 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
18d90 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
18da0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
18db0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 ors.**.** ^This
18dc0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 routine sets a c
18dd0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
18de0 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 that might be i
18df0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a nvoked whenever.
18e00 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 ** an attempt is
18e10 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 made to open a
18e20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 database table t
18e30 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hat another thre
18e40 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 ad.** or process
18e50 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a has locked..**.
18e60 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 ** ^If the busy
18e70 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
18e80 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
18e90 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f USY] or [SQLITE_
18ea0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a IOERR_BLOCKED].*
18eb0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
18ec0 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
18ed0 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
18ee0 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 lock. ^If the b
18ef0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 usy callback.**
18f00 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
18f10 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d n the callback m
18f20 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 ight be invoked
18f30 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e with two argumen
18f40 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ts..**.** ^The f
18f50 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
18f60 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
18f70 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 r is a copy of t
18f80 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 he void* pointer
18f90 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 which.** is the
18fa0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
18fb0 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f to sqlite3_busy_
18fc0 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 handler(). ^The
18fd0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
18fe0 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 to.** the busy
18ff0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
19000 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
19010 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 f times that the
19020 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 busy handler ha
19030 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 s.** been invoke
19040 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 d for this locki
19050 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
19060 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 he.** busy callb
19070 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 ack returns 0, t
19080 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 hen no additiona
19090 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d l attempts are m
190a0 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 ade to.** access
190b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e the database an
190c0 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 d [SQLITE_BUSY]
190d0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 or [SQLITE_IOERR
190e0 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 _BLOCKED] is ret
190f0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 urned..** ^If th
19100 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
19110 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
19120 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 n another attemp
19130 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 t.** is made to
19140 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
19150 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e e for reading an
19160 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 d the cycle repe
19170 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 ats..**.** The p
19180 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 resence of a bus
19190 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e y handler does n
191a0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 ot guarantee tha
191b0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 t it will be inv
191c0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 oked.** when the
191d0 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 re is lock conte
191e0 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 ntion. ^If SQLit
191f0 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 e determines tha
19200 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 t invoking the b
19210 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 usy.** handler c
19220 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 ould result in a
19230 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 deadlock, it wi
19240 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 ll go ahead and
19250 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 return [SQLITE_B
19260 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 USY].** or [SQLI
19270 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
19280 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 ] instead of inv
19290 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 oking the busy h
192a0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 andler..** Consi
192b0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 der a scenario w
192c0 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 here one process
192d0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
192e0 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 ad lock that.**
192f0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 it is trying to
19300 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 promote to a res
19310 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a erved lock and.*
19320 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 * a second proce
19330 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
19340 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 reserved lock th
19350 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a at it is trying.
19360 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ** to promote to
19370 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f an exclusive lo
19380 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ck. The first p
19390 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 rocess cannot pr
193a0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 oceed.** because
193b0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
193c0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 y the second and
193d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
193e0 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 ess cannot.** pr
193f0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 oceed because it
19400 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
19410 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f he first. If bo
19420 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 th processes.**
19430 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 invoke the busy
19440 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 handlers, neithe
19450 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 r will make any
19460 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 progress. There
19470 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 fore,.** SQLite
19480 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
19490 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 BUSY] for the fi
194a0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 rst process, hop
194b0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a ing that this.**
194c0 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 will induce the
194d0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 first process t
194e0 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 o release its re
194f0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f ad lock and allo
19500 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 w.** the second
19510 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 process to proce
19520 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 ed..**.** ^The d
19530 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c efault busy call
19540 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a back is NULL..**
19550 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
19560 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 _BUSY] error is
19570 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 converted to [SQ
19580 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
19590 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 ED].** when SQLi
195a0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 te is in the mid
195b0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 dle of a large t
195c0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 ransaction where
195d0 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e all the.** chan
195e0 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 ges will not fit
195f0 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d into the in-mem
19600 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 ory cache. SQLi
19610 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 te will.** alrea
19620 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 dy hold a RESERV
19630 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 ED lock on the d
19640 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 atabase file, bu
19650 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f t it needs.** to
19660 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f promote this lo
19670 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 ck to EXCLUSIVE
19680 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 so that it can s
19690 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 pill cache.** pa
196a0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 ges into the dat
196b0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f abase file witho
196c0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 ut harm to concu
196d0 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 rrent.** readers
196e0 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 . ^If it is una
196f0 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ble to promote t
19700 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 he lock, then th
19710 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 e in-memory.** c
19720 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 ache will be lef
19730 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 t in an inconsis
19740 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 tent state and s
19750 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 o the error.** c
19760 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 ode is promoted
19770 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 from the relativ
19780 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 ely benign [SQLI
19790 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 TE_BUSY] to.** t
197a0 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b he more severe [
197b0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
197c0 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 CKED]. ^This er
197d0 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 ror code promoti
197e0 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 on.** forces an
197f0 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 automatic rollba
19800 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 ck of the change
19810 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c s. See the.** <
19820 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 a href="/cvstrac
19830 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 /wiki?p=Corrupti
19840 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 onFollowingBusyE
19850 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 rror">.** Corrup
19860 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 tionFollowingBus
19870 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 yError</a> wiki
19880 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 page for a discu
19890 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 ssion of why.**
198a0 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e this is importan
198b0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 t..**.** ^(There
198c0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 can only be a s
198d0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c ingle busy handl
198e0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 er defined for e
198f0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ach.** [database
19900 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 connection]. S
19910 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 etting a new bus
19920 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 y handler clears
19930 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 any.** previous
19940 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 ly set handler.)
19950 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 ^ ^Note that ca
19960 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 lling [sqlite3_b
19970 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a usy_timeout()].*
19980 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 * will also set
19990 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 or clear the bus
199a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a y handler..**.**
199b0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 The busy callba
199c0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 ck should not ta
199d0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 ke any actions w
199e0 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a hich modify the.
199f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
19a00 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
19a10 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
19a20 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 dler. Any such
19a30 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c actions.** resul
19a40 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 t in undefined b
19a50 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 ehavior..** .**
19a60 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d A busy handler m
19a70 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 ust not close th
19a80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
19a90 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 ction.** or [pre
19aa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
19ab0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
19ac0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a e busy handler..
19ad0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
19ae0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
19af0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
19b00 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e int(*)(void*,in
19b10 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a t), void*);../*.
19b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
19b30 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a A Busy Timeout.
19b40 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
19b50 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 ine sets a [sqli
19b60 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
19b70 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d | busy handler]
19b80 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 that sleeps.**
19b90 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 for a specified
19ba0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 amount of time w
19bb0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c hen a table is l
19bc0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e ocked. ^The han
19bd0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 dler.** will sle
19be0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
19bf0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 s until at least
19c00 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
19c10 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a ds of sleeping.*
19c20 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 * have accumulat
19c30 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c ed. ^After at l
19c40 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
19c50 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
19c60 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
19c70 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
19c80 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
19c90 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
19ca0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
19cb0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 BUSY] or [SQLITE
19cc0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e _IOERR_BLOCKED].
19cd0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
19ce0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
19cf0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 h an argument le
19d00 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
19d10 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e to zero.** turn
19d20 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 s off all busy h
19d30 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e andlers..**.** ^
19d40 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
19d50 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
19d60 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 handler for a p
19d70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 articular.** [da
19d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
19d90 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e n] any any given
19da0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f moment. If ano
19db0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 ther busy handle
19dc0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 r.** was defined
19dd0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 (using [sqlite
19de0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
19df0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c ]) prior to call
19e00 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 ing.** this rout
19e10 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 ine, that other
19e20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
19e30 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 cleared.)^.*/.SQ
19e40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
19e50 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
19e60 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
19e70 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ms);../*.** CAPI
19e80 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 3REF: Convenienc
19e90 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 e Routines For R
19ea0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a unning Queries.*
19eb0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c *.** This is a l
19ec0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 egacy interface
19ed0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 that is preserve
19ee0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 d for backwards
19ef0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
19f00 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e * Use of this in
19f10 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 terface is not r
19f20 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a ecommended..**.*
19f30 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 * Definition: A
19f40 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c <b>result table<
19f50 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 /b> is memory da
19f60 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 ta structure cre
19f70 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b ated by the.** [
19f80 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
19f90 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 e()] interface.
19fa0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
19fb0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 records the.** c
19fc0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 omplete query re
19fd0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f sults from one o
19fe0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a r more queries..
19ff0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 **.** The table
1a000 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 conceptually has
1a010 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 a number of row
1a020 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 s and columns.
1a030 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d But.** these num
1a040 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 bers are not par
1a050 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 t of the result
1a060 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 table itself. T
1a070 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 hese.** numbers
1a080 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 are obtained sep
1a090 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 arately. Let N
1a0a0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1a0b0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 rows.** and M b
1a0c0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 e the number of
1a0d0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 columns..**.** A
1a0e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 result table is
1a0f0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
1a100 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 nters to zero-te
1a110 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 rminated UTF-8 s
1a120 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 trings..** There
1a130 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 are (N+1)*M ele
1a140 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 ments in the arr
1a150 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d ay. The first M
1a160 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a pointers point.
1a170 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 ** to zero-termi
1a180 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 nated strings th
1a190 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 at contain the
1a1a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c names of the col
1a1b0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d umns..** The rem
1a1c0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 aining entries a
1a1d0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 ll point to quer
1a1e0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c y results. NULL
1a1f0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a values result.*
1a200 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 * in NULL pointe
1a210 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 rs. All other v
1a220 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 alues are in the
1a230 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 ir UTF-8 zero-te
1a240 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
1a250 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f ng representatio
1a260 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 n as returned by
1a270 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
1a280 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _text()]..**.**
1a290 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d A result table m
1a2a0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 ight consist of
1a2b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f one or more memo
1a2c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a ry allocations..
1a2d0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 ** It is not saf
1a2e0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 e to pass a resu
1a2f0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c lt table directl
1a300 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 y to [sqlite3_fr
1a310 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 ee()]..** A resu
1a320 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 lt table should
1a330 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 be deallocated u
1a340 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 sing [sqlite3_fr
1a350 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a ee_table()]..**.
1a360 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 ** ^(As an examp
1a370 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 le of the result
1a380 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 table format, s
1a390 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 uppose a query r
1a3a0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 esult.** is as f
1a3b0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1a3c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1a3d0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 ** Name
1a3e0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 | Age.**
1a3f0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------
1a400 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a -------------.**
1a410 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 Alice
1a420 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 | 43.**
1a430 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c Bob |
1a440 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 28.** Ci
1a450 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a ndy | 21.*
1a460 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1a470 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 uote>.**.** Ther
1a480 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e e are two column
1a490 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 (M==2) and thre
1a4a0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 e rows (N==3).
1a4b0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 Thus the.** resu
1a4c0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 lt table has 8 e
1a4d0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 ntries. Suppose
1a4e0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c the result tabl
1a4f0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 e is stored.** i
1a500 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 n an array names
1a510 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e azResult. Then
1a520 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 azResult holds
1a530 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a this content:.**
1a540 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1a550 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
1a560 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 azResult[0]
1a570 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 = "Name";.**
1a580 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1a590 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 ;1] = "Age";.**
1a5a0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1a5b0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 #91;2] = "Alice"
1a5c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1a5d0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 sult[3] = "4
1a5e0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 3";.** az
1a5f0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 Result[4] =
1a600 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "Bob";.**
1a610 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d azResult[5]
1a620 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 = "28";.**
1a630 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1a640 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 6] = "Cindy";.**
1a650 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1a660 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a [7] = "21";.
1a670 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1a680 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e quote>)^.**.** ^
1a690 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
1a6a0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e table() function
1a6b0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f evaluates one o
1a6c0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f r more.** semico
1a6d0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 lon-separated SQ
1a6e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 L statements in
1a6f0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 the zero-termina
1a700 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 ted UTF-8.** str
1a710 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 ing of its 2nd p
1a720 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
1a730 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 urns a result ta
1a740 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f ble to the.** po
1a750 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 inter given in i
1a760 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 ts 3rd parameter
1a770 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 ..**.** After th
1a780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 e application ha
1a790 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
1a7a0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 the result from
1a7b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1a7c0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 e(),.** it must
1a7d0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 pass the result
1a7e0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f table pointer to
1a7f0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
1a800 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 ble() in order t
1a810 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 o.** release the
1a820 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 memory that was
1a830 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 malloced. Beca
1a840 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 use of the way t
1a850 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
1a860 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 alloc()] happens
1a870 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f within sqlite3_
1a880 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 get_table(), the
1a890 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 calling.** func
1a8a0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 tion must not tr
1a8b0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 y to call [sqlit
1a8c0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 e3_free()] direc
1a8d0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 tly. Only.** [s
1a8e0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
1a8f0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 e()] is able to
1a900 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f release the memo
1a910 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 ry properly and
1a920 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 safely..**.** Th
1a930 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
1a940 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
1a950 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 is implemented a
1a960 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 s a wrapper arou
1a970 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 nd.** [sqlite3_e
1a980 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c xec()]. The sql
1a990 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1a9a0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f routine does no
1a9b0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a t have access.**
1a9c0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c to any internal
1a9d0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 data structures
1a9e0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 of SQLite. It
1a9f0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 uses only the pu
1aa00 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 blic.** interfac
1aa10 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 e defined here.
1aa20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 As a consequenc
1aa30 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f e, errors that o
1aa40 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 ccur in the.** w
1aa50 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 rapper layer out
1aa60 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 side of the inte
1aa70 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 rnal [sqlite3_ex
1aa80 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e ec()] call are n
1aa90 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 ot.** reflected
1aaa0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
1aab0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f lls to [sqlite3_
1aac0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a errcode()] or.**
1aad0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
1aae0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
1aaf0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 PI int sqlite3_g
1ab00 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 et_table(. sqli
1ab10 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1ab20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 /* An open dat
1ab30 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
1ab40 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
1ab50 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
1ab60 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 aluated */. cha
1ab70 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 r ***pazResult,
1ab80 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 /* Results of
1ab90 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 the query */.
1aba0 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 int *pnRow,
1abb0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
1abc0 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 of result rows w
1abd0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
1abe0 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 int *pnColumn,
1abf0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
1ac00 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d of result colum
1ac10 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ns written here
1ac20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 */. char **pzEr
1ac30 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 rmsg /* Er
1ac40 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
1ac50 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 here */.);.SQLIT
1ac60 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
1ac70 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 e3_free_table(ch
1ac80 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f ar **result);../
1ac90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
1aca0 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 ormatted String
1acb0 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f Printing Functio
1acc0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 ns.**.** These r
1acd0 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b outines are work
1ace0 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 -alikes of the "
1acf0 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 printf()" family
1ad00 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a of functions.**
1ad10 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
1ad20 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
1ad30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1ad40 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 _mprintf() and s
1ad50 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
1ad60 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 ) routines write
1ad70 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 their.** result
1ad80 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 s into memory ob
1ad90 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c tained from [sql
1ada0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a ite3_malloc()]..
1adb0 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 ** The strings r
1adc0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1add0 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 two routines sh
1ade0 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 ould be.** relea
1adf0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f sed by [sqlite3_
1ae00 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 free()]. ^Both
1ae10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
1ae20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
1ae30 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 r if [sqlite3_ma
1ae40 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c lloc()] is unabl
1ae50 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e e to allocate en
1ae60 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 ough.** memory t
1ae70 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c o hold the resul
1ae80 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a ting string..**.
1ae90 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
1aea0 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 _snprintf() rout
1aeb0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 ine is similar t
1aec0 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 o "snprintf()" f
1aed0 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 rom.** the stand
1aee0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 ard C library.
1aef0 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 The result is wr
1af00 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a itten into the.*
1af10 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 * buffer supplie
1af20 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1af30 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 parameter whose
1af40 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 size is given by
1af50 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 .** the first pa
1af60 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 rameter. Note th
1af70 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 at the order of
1af80 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f the.** first two
1af90 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 parameters is r
1afa0 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 eversed from snp
1afb0 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 rintf().)^ This
1afc0 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 is an.** histor
1afd0 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 ical accident th
1afe0 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 at cannot be fix
1aff0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
1b000 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 ing.** backwards
1b010 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 compatibility.
1b020 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 ^(Note also tha
1b030 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e t sqlite3_snprin
1b040 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 tf().** returns
1b050 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 a pointer to its
1b060 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 buffer instead
1b070 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 of the number of
1b080 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 .** characters a
1b090 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 ctually written
1b0a0 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e into the buffer.
1b0b0 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 )^ We admit tha
1b0c0 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 t.** the number
1b0d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 of characters wr
1b0e0 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 itten would be a
1b0f0 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 more useful ret
1b100 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 urn.** value but
1b110 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 we cannot chang
1b120 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 e the implementa
1b130 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
1b140 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f snprintf().** no
1b150 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 w without breaki
1b160 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ng compatibility
1b170 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 ..**.** ^As long
1b180 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 as the buffer s
1b190 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 ize is greater t
1b1a0 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 han zero, sqlite
1b1b0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
1b1c0 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
1b1d0 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c the buffer is al
1b1e0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
1b1f0 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 ated. ^The firs
1b200 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 t.** parameter "
1b210 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 n" is the total
1b220 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
1b230 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 er, including sp
1b240 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a ace for.** the z
1b250 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
1b260 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 So the longest
1b270 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 string that can
1b280 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a be completely.**
1b290 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 written will be
1b2a0 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e n-1 characters.
1b2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1b2c0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 te3_vsnprintf()
1b2d0 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 routine is a var
1b2e0 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 args version of
1b2f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1b300 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ()..**.** These
1b310 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 routines all imp
1b320 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 lement some addi
1b330 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e tional formattin
1b340 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 g.** options tha
1b350 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 t are useful for
1b360 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 constructing SQ
1b370 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
1b380 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 All of the usua
1b390 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 l printf() forma
1b3a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 tting options ap
1b3b0 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f ply. In additio
1b3c0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 n, there.** is a
1b3d0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 re "%q", "%Q", a
1b3e0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e nd "%z" options.
1b3f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 .**.** ^(The %q
1b400 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b option works lik
1b410 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 e %s in that it
1b420 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 substitutes a nu
1b430 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 l-terminated.**
1b440 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 string from the
1b450 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 argument list.
1b460 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 But %q also doub
1b470 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 les every '\'' c
1b480 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 haracter..** %q
1b490 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 is designed for
1b4a0 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 use inside a str
1b4b0 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 ing literal.)^
1b4c0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 By doubling each
1b4d0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 '\''.** charact
1b4e0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 er it escapes th
1b4f0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 at character and
1b500 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 allows it to be
1b510 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a inserted into.*
1b520 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a * the string..**
1b530 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c .** For example,
1b540 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 assume the stri
1b550 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 ng variable zTex
1b560 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 t contains text
1b570 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1b580 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1b590 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 re>.** char *zT
1b5a0 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 ext = "It's a ha
1b5b0 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f ppy day!";.** </
1b5c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1b5d0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 >.**.** One can
1b5e0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e use this text in
1b5f0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
1b600 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
1b610 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1b620 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1b630 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
1b640 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
1b650 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
1b660 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b ('%q')", zText);
1b670 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
1b680 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
1b690 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
1b6a0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
1b6b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1b6c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 ote>.**.** Becau
1b6d0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 se the %q format
1b6e0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c string is used,
1b6f0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 the '\'' charac
1b700 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 ter in zText.**
1b710 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 is escaped and t
1b720 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 he SQL generated
1b730 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a is as follows:.
1b740 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1b750 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 e><pre>.** INSE
1b760 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 RT INTO table1 V
1b770 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 ALUES('It''s a h
1b780 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c appy day!').** <
1b790 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1b7a0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 e>.**.** This is
1b7b0 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 correct. Had w
1b7c0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 e used %s instea
1b7d0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e d of %q, the gen
1b7e0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f erated SQL.** wo
1b7f0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 uld have looked
1b800 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a like this:.**.**
1b810 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1b820 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
1b830 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
1b840 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 ('It's a happy d
1b850 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ay!');.** </pre>
1b860 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1b870 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 .** This second
1b880 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 example is an SQ
1b890 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 L syntax error.
1b8a0 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 As a general ru
1b8b0 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a le you should.**
1b8c0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 always use %q i
1b8d0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 nstead of %s whe
1b8e0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 n inserting text
1b8f0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c into a string l
1b900 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 iteral..**.** ^(
1b910 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f The %Q option wo
1b920 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 rks like %q exce
1b930 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 pt it also adds
1b940 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 single quotes ar
1b950 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 ound.** the outs
1b960 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c ide of the total
1b970 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 string. Additi
1b980 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 onally, if the p
1b990 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a arameter in the.
1b9a0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 ** argument list
1b9b0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1b9c0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 er, %Q substitut
1b9d0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c es the text "NUL
1b9e0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 L" (without.** s
1b9f0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e ingle quotes).)^
1ba00 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c So, for exampl
1ba10 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 e, one could say
1ba20 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1ba30 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
1ba40 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 ar *zSQL = sqlit
1ba50 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 e3_mprintf("INSE
1ba60 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 RT INTO table VA
1ba70 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 LUES(%Q)", zText
1ba80 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
1ba90 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
1baa0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
1bab0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
1bac0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1bad0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1bae0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c code above will
1baf0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 render a correc
1bb00 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 t SQL statement
1bb10 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 in the zSQL.** v
1bb20 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 ariable even if
1bb30 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 the zText variab
1bb40 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 le is a NULL poi
1bb50 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 nter..**.** ^(Th
1bb60 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e e "%z" formattin
1bb70 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c g option works l
1bb80 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 ike "%s" but wit
1bb90 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f h the.** additio
1bba0 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 n that after the
1bbb0 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e string has been
1bbc0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 read and copied
1bbd0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 into.** the res
1bbe0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ult, [sqlite3_fr
1bbf0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 ee()] is called
1bc00 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 on the input str
1bc10 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 ing.)^.*/.SQLITE
1bc20 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 _API char *sqlit
1bc30 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 e3_mprintf(const
1bc40 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c char*,...);.SQL
1bc50 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 ITE_API char *sq
1bc60 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 lite3_vmprintf(c
1bc70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c onst char*, va_l
1bc80 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ist);.SQLITE_API
1bc90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 char *sqlite3_s
1bca0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
1bcb0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
1bcc0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..);.SQLITE_API
1bcd0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 char *sqlite3_vs
1bce0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
1bcf0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 *,const char*, v
1bd00 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 a_list);../*.**
1bd10 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
1bd20 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 Allocation Subs
1bd30 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ystem.**.** The
1bd40 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 SQLite core uses
1bd50 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 these three rou
1bd60 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 tines for all of
1bd70 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 its own.** inte
1bd80 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rnal memory allo
1bd90 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 cation needs. "C
1bda0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 ore" in the prev
1bdb0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a ious sentence.**
1bdc0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 does not includ
1bdd0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 e operating-syst
1bde0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 em specific VFS
1bdf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 implementation.
1be00 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 The.** Windows
1be10 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 VFS uses native
1be20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 malloc() and fre
1be30 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 e() for some ope
1be40 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e rations..**.** ^
1be50 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c The sqlite3_mall
1be60 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 oc() routine ret
1be70 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1be80 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 o a block.** of
1be90 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 memory at least
1bea0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 N bytes in lengt
1beb0 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 h, where N is th
1bec0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 e parameter..**
1bed0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ^If sqlite3_mall
1bee0 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 oc() is unable t
1bef0 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 o obtain suffici
1bf00 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f ent free.** memo
1bf10 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 ry, it returns a
1bf20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
1bf30 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 ^If the paramete
1bf40 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 r N to.** sqlite
1bf50 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 3_malloc() is ze
1bf60 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 ro or negative t
1bf70 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c hen sqlite3_mall
1bf80 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 oc() returns.**
1bf90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
1bfa0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
1bfb0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
1bfc0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
1bfd0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
1bfe0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
1bff0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1c000 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
1c010 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
1c020 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
1c030 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
1c040 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 ^The sqlite3_f
1c050 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
1c060 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
1c070 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1c080 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
1c090 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
1c0a0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
1c0b0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
1c0c0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
1c0d0 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
1c0e0 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
1c0f0 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
1c100 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
1c110 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
1c120 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
1c130 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
1c140 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
1c150 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
1c160 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
1c170 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
1c180 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
1c190 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
1c1a0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1c1b0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
1c1c0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
1c1d0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
1c1e0 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
1c1f0 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
1c200 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
1c210 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1c220 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1c230 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 ealloc()..**.**
1c240 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^(The sqlite3_re
1c250 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 alloc() interfac
1c260 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 e attempts to re
1c270 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 size a.** prior
1c280 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1c290 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 n to be at least
1c2a0 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 N bytes, where
1c2b0 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f N is the.** seco
1c2c0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 nd parameter. T
1c2d0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
1c2e0 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a tion to be resiz
1c2f0 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a ed is the first.
1c300 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 ** parameter.)^
1c310 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 ^ If the first p
1c320 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1c330 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a te3_realloc().**
1c340 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1c350 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 er then its beha
1c360 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 vior is identica
1c370 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 l to calling.**
1c380 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e sqlite3_malloc(N
1c390 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 ) where N is the
1c3a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1c3b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 r to sqlite3_rea
1c3c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 lloc()..** ^If t
1c3d0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1c3e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
1c3f0 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f ealloc() is zero
1c400 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 or.** negative
1c410 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
1c420 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 r is exactly the
1c430 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 same as calling
1c440 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
1c450 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 (P) where P is t
1c460 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1c470 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1c480 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c alloc()..** ^sql
1c490 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
1c4a0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1c4b0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c to a memory all
1c4c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 ocation.** of at
1c4d0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
1c4e0 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 n size or NULL i
1c4f0 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d f sufficient mem
1c500 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 ory is unavailab
1c510 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 le..** ^If M is
1c520 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
1c530 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1c540 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 , then min(N,M)
1c550 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 bytes.** of the
1c560 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e prior allocation
1c570 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f are copied into
1c580 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
1c590 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 f buffer returne
1c5a0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f d.** by sqlite3_
1c5b0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 realloc() and th
1c5c0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1c5d0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
1c5e0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
1c5f0 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 loc() returns NU
1c600 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 LL, then the pri
1c610 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a or allocation.**
1c620 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a is not freed..*
1c630 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 *.** ^The memory
1c640 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
1c650 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e ite3_malloc() an
1c660 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f d sqlite3_reallo
1c670 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 c().** is always
1c680 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c aligned to at l
1c690 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 east an 8 byte b
1c6a0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 oundary, or to a
1c6b0 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 .** 4 byte bound
1c6c0 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 ary if the [SQLI
1c6d0 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 TE_4_BYTE_ALIGNE
1c6e0 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c D_MALLOC] compil
1c6f0 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
1c700 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
1c710 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f In SQLite versio
1c720 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e n 3.5.0 and 3.5.
1c730 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 1, it was possib
1c740 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 le to define.**
1c750 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f the SQLITE_OMIT_
1c760 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f MEMORY_ALLOCATIO
1c770 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 N which would ca
1c780 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e use the built-in
1c790 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
1c7a0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 on of these rout
1c7b0 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 ines to be omitt
1c7c0 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 ed. That capabi
1c7d0 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f lity.** is no lo
1c7e0 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 nger provided.
1c7f0 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 Only built-in me
1c800 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 mory allocators
1c810 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a can be used..**.
1c820 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 ** Prior to SQLi
1c830 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 te version 3.7.1
1c840 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 0, the Windows O
1c850 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
1c860 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 r called.** the
1c870 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
1c880 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 and free() direc
1c890 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 tly when convert
1c8a0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 ing.** filenames
1c8b0 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 between the UTF
1c8c0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 -8 encoding used
1c8d0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e by SQLite.** an
1c8e0 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e d whatever filen
1c8f0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ame encoding is
1c900 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 used by the part
1c910 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a icular Windows.*
1c920 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 * installation.
1c930 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
1c940 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 on errors were d
1c950 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 etected, but.**
1c960 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 they were report
1c970 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 ed back as [SQLI
1c980 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a TE_CANTOPEN] or.
1c990 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 ** [SQLITE_IOERR
1c9a0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 ] rather than [S
1c9b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a QLITE_NOMEM]..**
1c9c0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 .** The pointer
1c9d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 arguments to [sq
1c9e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e lite3_free()] an
1c9f0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
1ca00 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 oc()].** must be
1ca10 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 either NULL or
1ca20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 else pointers ob
1ca30 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 tained from a pr
1ca40 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f ior.** invocatio
1ca50 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 n of [sqlite3_ma
1ca60 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 lloc()] or [sqli
1ca70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 te3_realloc()] t
1ca80 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 hat have.** not
1ca90 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 yet been release
1caa0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 d..**.** The app
1cab0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
1cac0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 t read or write
1cad0 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 any part of.** a
1cae0 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 block of memory
1caf0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
1cb00 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e en released usin
1cb10 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 g.** [sqlite3_fr
1cb20 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ee()] or [sqlite
1cb30 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 3_realloc()]..*/
1cb40 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
1cb50 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 *sqlite3_malloc
1cb60 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 (int);.SQLITE_AP
1cb70 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f I void *sqlite3_
1cb80 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 realloc(void*, i
1cb90 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
1cba0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 void sqlite3_fre
1cbb0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a e(void*);../*.**
1cbc0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1cbd0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 y Allocator Stat
1cbe0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c istics.**.** SQL
1cbf0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 ite provides the
1cc00 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 se two interface
1cc10 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 s for reporting
1cc20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a on the status.**
1cc30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
1cc40 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c _malloc()], [sql
1cc50 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e ite3_free()], an
1cc60 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d [sqlite3_reall
1cc70 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 oc()].** routine
1cc80 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 s, which form th
1cc90 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 e built-in memor
1cca0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 y allocation sub
1ccb0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 system..**.** ^T
1ccc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
1ccd0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 ry_used()] routi
1cce0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ne returns the n
1ccf0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a umber of bytes.*
1cd00 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 * of memory curr
1cd10 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e ently outstandin
1cd20 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 g (malloced but
1cd30 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e not freed)..** ^
1cd40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
1cd50 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d ory_highwater()]
1cd60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
1cd70 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
1cd80 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 value of [sqlite
1cd90 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
1cda0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d since the high-
1cdb0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 water mark.** wa
1cdc0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e s last reset. ^
1cdd0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 The values retur
1cde0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
1cdf0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 memory_used()] a
1ce00 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d nd.** [sqlite3_m
1ce10 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1ce20 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f )] include any o
1ce30 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 verhead.** added
1ce40 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 by SQLite in it
1ce50 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
1ce60 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c of [sqlite3_mal
1ce70 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e loc()],.** but n
1ce80 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 ot overhead adde
1ce90 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 d by the any und
1cea0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c erlying system l
1ceb0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e ibrary.** routin
1cec0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 es that [sqlite3
1ced0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 _malloc()] may c
1cee0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 all..**.** ^The
1cef0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 memory high-wate
1cf00 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 r mark is reset
1cf10 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 to the current v
1cf20 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 alue of.** [sqli
1cf30 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1cf40 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 )] if and only i
1cf50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
1cf60 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d to.** [sqlite3_m
1cf70 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1cf80 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 )] is true. ^Th
1cf90 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1cfa0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f .** by [sqlite3_
1cfb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
1cfc0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 (1)] is the high
1cfd0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 -water mark.** p
1cfe0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 rior to the rese
1cff0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 t..*/.SQLITE_API
1d000 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
1d010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
1d020 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 ed(void);.SQLITE
1d030 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
1d040 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
1d050 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 y_highwater(int
1d060 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a resetFlag);../*.
1d070 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 ** CAPI3REF: Pse
1d080 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 udo-Random Numbe
1d090 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a r Generator.**.*
1d0a0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e * SQLite contain
1d0b0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 s a high-quality
1d0c0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e pseudo-random n
1d0d0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 umber generator
1d0e0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a (PRNG) used to.*
1d0f0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 * select random
1d100 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d [ROWID | ROWIDs]
1d110 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 when inserting
1d120 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f new records into
1d130 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a a table that.**
1d140 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 already uses th
1d150 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 e largest possib
1d160 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 le [ROWID]. The
1d170 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 PRNG is also us
1d180 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 ed for.** the bu
1d190 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 ild-in random()
1d1a0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 and randomblob()
1d1b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 SQL functions.
1d1c0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 This interface
1d1d0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 allows.** applic
1d1e0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 ations to access
1d1f0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 the same PRNG f
1d200 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 or other purpose
1d210 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c s..**.** ^A call
1d220 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
1d230 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 stores N bytes
1d240 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e of randomness in
1d250 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 to buffer P..**
1d260 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 ^If N is less th
1d270 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63 an one, then P c
1d280 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 an be a NULL poi
1d290 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 nter..**.** ^If
1d2a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 this routine has
1d2b0 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f not been previo
1d2c0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 usly called or i
1d2d0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a f the previous.*
1d2e0 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 * call had N les
1d2f0 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e s than one, then
1d300 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 the PRNG is see
1d310 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d ded using random
1d320 6e 65 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 ness.** obtained
1d330 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f from the xRando
1d340 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 mness method of
1d350 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
1d360 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
1d370 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 ..** ^If the pre
1d380 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
1d390 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 is routine had a
1d3a0 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 n N of 1 or more
1d3b0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65 then.** the pse
1d3c0 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 udo-randomness i
1d3d0 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 s generated.** i
1d3e0 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 nternally and wi
1d3f0 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 thout recourse t
1d400 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
1d410 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a fs] xRandomness.
1d420 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 ** method..*/.SQ
1d430 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
1d440 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 lite3_randomness
1d450 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 (int N, void *P)
1d460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1d470 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 F: Compile-Time
1d480 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 Authorization Ca
1d490 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 llbacks.**.** ^T
1d4a0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
1d4b0 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 sters an authori
1d4c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 zer callback wit
1d4d0 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a h a particular.*
1d4e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1d4f0 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 ection], supplie
1d500 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 d in the first a
1d510 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
1d520 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1d530 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
1d540 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 as SQL statement
1d550 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 s are being comp
1d560 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 iled.** by [sqli
1d570 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
1d580 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b r its variants [
1d590 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1d5a0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
1d5b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
1d5c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
1d5d0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e pare16_v2()]. ^
1d5e0 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f At various.** po
1d5f0 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 ints during the
1d600 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 compilation proc
1d610 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 ess, as logic is
1d620 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a being created.*
1d630 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 * to perform var
1d640 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 ious actions, th
1d650 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1d660 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
1d670 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 to.** see if th
1d680 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 ose actions are
1d690 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 allowed. ^The a
1d6a0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1d6b0 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ck should.** ret
1d6c0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
1d6d0 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 to allow the act
1d6e0 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e ion, [SQLITE_IGN
1d6f0 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 ORE] to disallow
1d700 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
1d710 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f action but allo
1d720 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d w the SQL statem
1d730 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 ent to continue
1d740 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 to be.** compile
1d750 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 d, or [SQLITE_DE
1d760 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 NY] to cause the
1d770 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 entire SQL stat
1d780 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 ement to be.** r
1d790 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 ejected with an
1d7a0 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 error. ^If the
1d7b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1d7c0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ack returns.** a
1d7d0 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
1d7e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f han [SQLITE_IGNO
1d7f0 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d RE], [SQLITE_OK]
1d800 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
1d810 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b Y].** then the [
1d820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1d830 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
1d840 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
1d850 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 iggered.** the a
1d860 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
1d870 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
1d880 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
1d890 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
1d8a0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
1d8b0 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 TE_OK], that mea
1d8c0 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e ns the operation
1d8d0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 .** requested is
1d8e0 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 ok. ^When the
1d8f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1d900 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
1d910 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1d920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
1d930 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
1d940 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
1d950 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
1d960 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
1d970 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
1d980 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 e explaining tha
1d990 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 t.** access is d
1d9a0 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 enied. .**.** ^T
1d9b0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1d9c0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
1d9d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
1d9e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
1d9f0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
1da00 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
1da10 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
1da20 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 ) interface. ^Th
1da30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1da40 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c er.** to the cal
1da50 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
1da60 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 ger [SQLITE_COPY
1da70 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
1da80 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
1da90 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 * the particular
1daa0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
1dab0 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 thorized. ^The t
1dac0 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
1dad0 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a th parameters.**
1dae0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1daf0 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e are zero-termin
1db00 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
1db10 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 t contain additi
1db20 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 onal.** details
1db30 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e about the action
1db40 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
1db50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
1db60 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
1db70 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a [SQLITE_READ].**
1db80 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
1db90 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
1dba0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
1dbb0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
1dbc0 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 statement] state
1dbd0 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 ment is construc
1dbe0 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 ted to substitut
1dbf0 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 e.** a NULL valu
1dc00 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 e in place of th
1dc10 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 e table column t
1dc20 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a hat would have.*
1dc30 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b * been read if [
1dc40 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
1dc50 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 een returned. T
1dc60 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 he [SQLITE_IGNOR
1dc70 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e E].** return can
1dc80 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 be used to deny
1dc90 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 an untrusted us
1dca0 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 er access to ind
1dcb0 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d ividual.** colum
1dcc0 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a ns of a table..*
1dcd0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e * ^If the action
1dce0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 code is [SQLITE
1dcf0 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 _DELETE] and the
1dd00 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1dd10 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e s.** [SQLITE_IGN
1dd20 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 ORE] then the [D
1dd30 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e ELETE] operation
1dd40 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 proceeds but th
1dd50 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f e.** [truncate o
1dd60 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 ptimization] is
1dd70 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c disabled and all
1dd80 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 rows are delete
1dd90 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a d individually..
1dda0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 **.** An authori
1ddb0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e zer is used when
1ddc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1ddd0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a e | preparing].*
1dde0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
1ddf0 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 from an untrust
1de00 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e ed source, to en
1de10 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 sure that the SQ
1de20 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1de30 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 do not try to ac
1de40 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 cess data they a
1de50 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 re not allowed t
1de60 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 o see, or that t
1de70 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 hey do not.** tr
1de80 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c y to execute mal
1de90 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 icious statement
1dea0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 s that damage th
1deb0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 e database. For
1dec0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 .** example, an
1ded0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 application may
1dee0 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 allow a user to
1def0 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a enter arbitrary.
1df00 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 ** SQL queries f
1df10 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 or evaluation by
1df20 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 a database. Bu
1df30 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
1df40 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 n does.** not wa
1df50 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 nt the user to b
1df60 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 e able to make a
1df70 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 rbitrary changes
1df80 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 to the.** datab
1df90 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 ase. An authori
1dfa0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 zer could then b
1dfb0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 e put in place w
1dfc0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 hile the.** user
1dfd0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 -entered SQL is
1dfe0 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 being [sqlite3_p
1dff0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 repare | prepare
1e000 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c d] that.** disal
1e010 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 lows everything
1e020 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 except [SELECT]
1e030 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
1e040 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * Applications t
1e050 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 hat need to proc
1e060 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 ess SQL from unt
1e070 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a rusted sources.*
1e080 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e * might also con
1e090 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 sider lowering r
1e0a0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 esource limits u
1e0b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
1e0c0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 mit()].** and li
1e0d0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 miting database
1e0e0 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b size using the [
1e0f0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
1e100 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 [PRAGMA].** in a
1e110 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 ddition to using
1e120 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a an authorizer..
1e130 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 **.** ^(Only a s
1e140 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 ingle authorizer
1e150 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 can be in place
1e160 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 on a database c
1e170 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 onnection.** at
1e180 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 a time. Each ca
1e190 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 ll to sqlite3_se
1e1a0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 t_authorizer ove
1e1b0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 rrides the.** pr
1e1c0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 evious call.)^
1e1d0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 ^Disable the aut
1e1e0 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 horizer by insta
1e1f0 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c lling a NULL cal
1e200 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 lback..** The au
1e210 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 thorizer is disa
1e220 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
1e230 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
1e240 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
1e250 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
1e260 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
1e270 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
1e280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1e290 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
1e2a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1e2b0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 back..** Note th
1e2c0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
1e2d0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
1e2e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
1e2f0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
1e300 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
1e310 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
1e320 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
1e330 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
1e340 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 agraph..**.** ^W
1e350 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
1e360 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 pare_v2()] is us
1e370 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 ed to prepare a
1e380 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a statement, the.*
1e390 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 * statement migh
1e3a0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 t be re-prepared
1e3b0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 during [sqlite3
1e3c0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 _step()] due to
1e3d0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 a .** schema cha
1e3e0 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 nge. Hence, the
1e3f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
1e400 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 uld ensure that
1e410 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 the.** correct a
1e420 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1e430 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c ck remains in pl
1e440 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b ace during the [
1e450 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
1e460 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 .**.** ^Note tha
1e470 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 t the authorizer
1e480 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1e490 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 oked only during
1e4a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
1e4b0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 pare()] or its v
1e4c0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 ariants. Author
1e4d0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a ization is not.*
1e4e0 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 * performed duri
1e4f0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 ng statement eva
1e500 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 luation in [sqli
1e510 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c te3_step()], unl
1e520 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 ess.** as stated
1e530 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
1e540 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 paragraph, sqli
1e550 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b te3_step() invok
1e560 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 es.** sqlite3_pr
1e570 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 epare_v2() to re
1e580 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d prepare a statem
1e590 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 ent after a sche
1e5a0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 ma change..*/.SQ
1e5b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1e5c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
1e5d0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c zer(. sqlite3*,
1e5e0 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 . int (*xAuth)(
1e5f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
1e600 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1e610 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
1e620 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f nst char*),. vo
1e630 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b id *pUserData.);
1e640 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1e650 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 : Authorizer Ret
1e660 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 urn Codes.**.**
1e670 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
1e680 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
1e690 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1e6a0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 k function] must
1e6b0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 .** return eithe
1e6c0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 r [SQLITE_OK] or
1e6d0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 one of these tw
1e6e0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f o constants in o
1e6f0 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 rder.** to signa
1e700 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 l SQLite whether
1e710 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 or not the acti
1e720 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e on is permitted.
1e730 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 See the.** [sq
1e740 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1e750 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
1e760 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d r documentation]
1e770 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
1e780 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
1e790 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
1e7a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 SQLITE_IGNORE is
1e7b0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 also used as a
1e7c0 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b [SQLITE_ROLLBACK
1e7d0 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a | return code].
1e7e0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c ** from the [sql
1e7f0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e ite3_vtab_on_con
1e800 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 flict()] interfa
1e810 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ce..*/.#define S
1e820 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 QLITE_DENY 1
1e830 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 /* Abort the SQ
1e840 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 L statement with
1e850 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 an error */.#de
1e860 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f fine SQLITE_IGNO
1e870 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 RE 2 /* Don't
1e880 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 allow access, bu
1e890 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 t don't generate
1e8a0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a an error */../*
1e8b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 .** CAPI3REF: Au
1e8c0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 thorizer Action
1e8d0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 Codes.**.** The
1e8e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 [sqlite3_set_aut
1e8f0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 horizer()] inter
1e900 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 face registers a
1e910 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1e920 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e on.** that is in
1e930 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 voked to authori
1e940 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 ze certain SQL s
1e950 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 tatement actions
1e960 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
1e970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1e980 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
1e990 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 integer code th
1e9a0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 at specifies.**
1e9b0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 what action is b
1e9c0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e eing authorized.
1e9d0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 These are the
1e9e0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 integer action c
1e9f0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 odes that.** the
1ea00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1ea10 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 back may be pass
1ea20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
1ea30 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 action code valu
1ea40 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 es signify what
1ea50 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f kind of operatio
1ea60 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 n is to be.** au
1ea70 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 thorized. The 3
1ea80 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d rd and 4th param
1ea90 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 eters to the aut
1eaa0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 horization.** ca
1eab0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1eac0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 will be paramete
1ead0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e rs or NULL depen
1eae0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 ding on which of
1eaf0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 these.** codes
1eb00 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 is used as the s
1eb10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e econd parameter.
1eb20 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 ^(The 5th para
1eb30 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 meter to the.**
1eb40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1eb50 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ack is the name
1eb60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
1eb70 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c ("main", "temp",
1eb80 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 .** etc.) if app
1eb90 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 licable.)^ ^The
1eba0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6th parameter t
1ebb0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
1ebc0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 callback.** is
1ebd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
1ebe0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 inner-most trigg
1ebf0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 er or view that
1ec00 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
1ec10 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 or.** the access
1ec20 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c attempt or NULL
1ec30 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 if this access
1ec40 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 attempt is direc
1ec50 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d tly from.** top-
1ec60 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a level SQL code..
1ec70 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
1ec80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1ec90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 ***************
1eca0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3rd ************
1ecb0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 4th ***********
1ecc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ecd0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 _CREATE_INDEX
1ece0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 1 /* In
1ecf0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
1ed00 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1ed10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ed20 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 CREATE_TABLE
1ed30 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 2 /* Tab
1ed40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1ed50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1ed60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1ed70 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 REATE_TEMP_INDEX
1ed80 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 3 /* Inde
1ed90 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
1eda0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1edb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1edc0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 EATE_TEMP_TABLE
1edd0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 4 /* Table
1ede0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1edf0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1ee00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1ee10 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ATE_TEMP_TRIGGER
1ee20 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 5 /* Trigge
1ee30 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
1ee40 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1ee50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1ee60 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 TE_TEMP_VIEW
1ee70 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6 /* View Na
1ee80 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
1ee90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1eea0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1eeb0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 E_TRIGGER
1eec0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 7 /* Trigger
1eed0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
1eee0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1eef0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1ef00 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
1ef10 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 8 /* View Name
1ef20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1ef30 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1ef40 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 e SQLITE_DELETE
1ef50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 9
1ef60 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1ef70 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1ef80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1ef90 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 SQLITE_DROP_IND
1efa0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 EX 10
1efb0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 /* Index Name
1efc0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 Table Name
1efd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1efe0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c SQLITE_DROP_TABL
1eff0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 E 11
1f000 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
1f010 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1f020 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1f030 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f QLITE_DROP_TEMP_
1f040 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 INDEX 12
1f050 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
1f060 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1f070 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f080 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 LITE_DROP_TEMP_T
1f090 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f ABLE 13 /
1f0a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1f0b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1f0c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f0d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 ITE_DROP_TEMP_TR
1f0e0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a IGGER 14 /*
1f0f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 Trigger Name
1f100 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1f110 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f120 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 TE_DROP_TEMP_VIE
1f130 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 W 15 /*
1f140 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 View Name
1f150 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f160 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f170 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 E_DROP_TRIGGER
1f180 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 16 /* T
1f190 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
1f1a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1f1b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f1c0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 _DROP_VIEW
1f1d0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 17 /* Vi
1f1e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
1f1f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1f200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f210 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 INSERT
1f220 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 18 /* Tab
1f230 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
1f240 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1f250 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
1f260 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
1f270 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 19 /* Prag
1f280 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 ma Name 1st
1f290 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 arg or NULL */.#
1f2a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
1f2b0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
1f2c0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 /* Table
1f2d0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d Name Colum
1f2e0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 n Name */.#d
1f2f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c efine SQLITE_SEL
1f300 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 ECT
1f310 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 21 /* NULL
1f320 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
1f330 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1f340 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
1f350 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 SACTION
1f360 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 22 /* Operati
1f370 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 on NULL
1f380 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1f390 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 ine SQLITE_UPDAT
1f3a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
1f3b0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 23 /* Table Na
1f3c0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e me Column N
1f3d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 ame */.#defi
1f3e0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 ne SQLITE_ATTACH
1f3f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
1f400 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 4 /* Filename
1f410 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
1f420 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1f430 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 e SQLITE_DETACH
1f440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
1f450 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e /* Database N
1f460 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 ame NULL
1f470 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1f480 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 SQLITE_ALTER_TA
1f490 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 BLE 26
1f4a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
1f4b0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 me Table Name
1f4c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1f4d0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 SQLITE_REINDEX
1f4e0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 27
1f4f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1f500 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
1f510 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1f520 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 QLITE_ANALYZE
1f530 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 28
1f540 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1f550 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1f560 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f570 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 LITE_CREATE_VTAB
1f580 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f LE 29 /
1f590 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1f5a0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 Module Name
1f5b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f5c0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 ITE_DROP_VTABLE
1f5d0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 30 /*
1f5e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1f5f0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
1f600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f610 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 TE_FUNCTION
1f620 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 31 /*
1f630 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f640 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 Function Name
1f650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f660 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 E_SAVEPOINT
1f670 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 32 /* O
1f680 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 peration S
1f690 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a avepoint Name *
1f6a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f6b0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 _COPY
1f6c0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 0 /* No
1f6d0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a longer used */.
1f6e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
1f6f0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 ECURSIVE
1f700 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 33 /* NULL
1f710 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c NULL
1f720 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a */..
1f730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1f740 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 Tracing And Prof
1f750 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a iling Functions.
1f760 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1f770 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 ines register ca
1f780 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 llback functions
1f790 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 that can be use
1f7a0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 d for.** tracing
1f7b0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 and profiling t
1f7c0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 he execution of
1f7d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
1f7e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 **.** ^The callb
1f7f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 ack function reg
1f800 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 istered by sqlit
1f810 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e e3_trace() is in
1f820 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 voked at.** vari
1f830 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 ous times when a
1f840 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
1f850 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 is being run by
1f860 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1f870 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
1f880 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
1f890 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 ck is invoked wi
1f8a0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 th a UTF-8 rende
1f8b0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 ring of the.** S
1f8c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
1f8d0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 t as the stateme
1f8e0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 nt first begins
1f8f0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 executing..** ^(
1f900 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 Additional sqlit
1f910 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 e3_trace() callb
1f920 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 acks might occur
1f930 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 .** as each trig
1f940 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d gered subprogram
1f950 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 is entered. Th
1f960 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 e callbacks for
1f970 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 triggers.** cont
1f980 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 ain a UTF-8 SQL
1f990 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 comment that ide
1f9a0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 ntifies the trig
1f9b0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ger.)^.**.** The
1f9c0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 [SQLITE_TRACE_S
1f9d0 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 IZE_LIMIT] compi
1f9e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 le-time option c
1f9f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 an be used to li
1fa00 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 mit.** the lengt
1fa10 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 h of [bound para
1fa20 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e meter] expansion
1fa30 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f in the output o
1fa40 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 f sqlite3_trace(
1fa50 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 )..**.** ^The ca
1fa60 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
1fa70 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 registered by sq
1fa80 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 lite3_profile()
1fa90 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 is invoked.** as
1faa0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d each SQL statem
1fab0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e ent finishes. ^
1fac0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c The profile call
1fad0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a back contains.**
1fae0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
1faf0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 atement text and
1fb00 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 an estimate of
1fb10 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a wall-clock time.
1fb20 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 ** of how long t
1fb30 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f hat statement to
1fb40 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 ok to run. ^The
1fb50 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 profile callbac
1fb60 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 k.** time is in
1fb70 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 units of nanosec
1fb80 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 onds, however th
1fb90 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d e current implem
1fba0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f entation.** is o
1fbb0 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d nly capable of m
1fbc0 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c illisecond resol
1fbd0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 ution so the six
1fbe0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 least significa
1fbf0 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 nt.** digits in
1fc00 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 the time are mea
1fc10 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 ningless. Futur
1fc20 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
1fc30 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 Lite.** might pr
1fc40 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 ovide greater re
1fc50 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 solution on the
1fc60 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 profiler callbac
1fc70 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 k. The.** sqlit
1fc80 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e e3_profile() fun
1fc90 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 ction is conside
1fca0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c red experimental
1fcb0 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 and is.** subje
1fcc0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 ct to change in
1fcd0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 future versions
1fce0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 of SQLite..*/.SQ
1fcf0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 LITE_API void *s
1fd00 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
1fd10 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
1fd20 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
1fd30 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
1fd40 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
1fd50 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
1fd60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 void *sqlite3_pr
1fd70 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a ofile(sqlite3*,.
1fd80 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c void(*xProfil
1fd90 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
1fda0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e har*,sqlite3_uin
1fdb0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f t64), void*);../
1fdc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 *.** CAPI3REF: Q
1fdd0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 uery Progress Ca
1fde0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 llbacks.**.** ^T
1fdf0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 he sqlite3_progr
1fe00 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c ess_handler(D,N,
1fe10 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 X,P) interface c
1fe20 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 auses the callba
1fe30 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 ck.** function X
1fe40 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 to be invoked p
1fe50 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
1fe60 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 ng long running
1fe70 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
1fe80 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
1fe90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
1fea0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f nd [sqlite3_get_
1feb0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 table()] for.**
1fec0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1fed0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 ion D. An examp
1fee0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
1fef0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
1ff00 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
1ff10 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
1ff20 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
1ff30 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 * ^The parameter
1ff40 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 P is passed thr
1ff50 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 ough as the only
1ff60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1ff70 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 e .** callback f
1ff80 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 unction X. ^The
1ff90 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 parameter N is
1ffa0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 the approximate
1ffb0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 number of .** [v
1ffc0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i
1ffd0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 nstructions] tha
1ffe0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 t are evaluated
1fff0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 between successi
20000 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e ve.** invocation
20010 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 s of the callbac
20020 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c k X. ^If N is l
20030 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 ess than one the
20040 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a n the progress.*
20050 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 * handler is dis
20060 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e abled..**.** ^On
20070 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
20080 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
20090 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
200a0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
200b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
200c0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
200d0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
200e0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
200f0 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
20100 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
20110 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
20120 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
20130 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
20140 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
20150 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
20160 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
20170 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
20180 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
20190 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
201a0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
201b0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
201c0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
201d0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
201e0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
201f0 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
20200 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
20210 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
20220 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
20230 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
20240 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
20250 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
20260 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
20270 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
20280 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
20290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
202a0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
202b0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
202c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
202d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
202e0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
202f0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
20300 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
20310 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20320 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
20330 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
20340 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
20350 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f h..**.*/.SQLITE_
20360 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
20370 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
20380 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c r(sqlite3*, int,
20390 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
203a0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
203b0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 API3REF: Opening
203c0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 A New Database
203d0 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a Connection.**.**
203e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
203f0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 open an SQLite
20400 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 database file as
20410 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
20420 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 e .** filename a
20430 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 rgument. ^The fi
20440 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 lename argument
20450 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
20460 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 s UTF-8 for.** s
20470 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
20480 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
20490 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 2() and as UTF-1
204a0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 6 in the native
204b0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f byte.** order fo
204c0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 r sqlite3_open16
204d0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 (). ^(A [databas
204e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 e connection] ha
204f0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a ndle is usually.
20500 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a ** returned in *
20510 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e ppDb, even if an
20520 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 error occurs.
20530 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 The only excepti
20540 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 on is that.** if
20550 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
20560 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 e to allocate me
20570 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
20580 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
20590 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c t,.** a NULL wil
205a0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 l be written int
205b0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 o *ppDb instead
205c0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 of a pointer to
205d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a the [sqlite3].**
205e0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 object.)^ ^(If
205f0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
20600 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 opened (and/or c
20610 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 reated) successf
20620 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 ully, then.** [S
20630 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 QLITE_OK] is ret
20640 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 urned. Otherwis
20650 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 e an [error code
20660 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e ] is returned.)^
20670 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 ^The.** [sqlite
20680 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 3_errmsg()] or [
20690 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
206a0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e ()] routines can
206b0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 be used to obta
206c0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 in.** an English
206d0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 language descri
206e0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 ption of the err
206f0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 or following a f
20700 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a ailure of any.**
20710 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
20720 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e open() routines.
20730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 .**.** ^The defa
20740 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 ult encoding for
20750 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 the database wi
20760 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a ll be UTF-8 if.*
20770 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
20780 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
20790 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 _v2() is called
207a0 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e and.** UTF-16 in
207b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
207c0 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 order if sqlite
207d0 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 3_open16() is us
207e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 ed..**.** Whethe
207f0 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f r or not an erro
20800 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 r occurs when it
20810 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f is opened, reso
20820 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 urces.** associa
20830 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 ted with the [da
20840 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20850 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 n] handle should
20860 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a be released by.
20870 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f ** passing it to
20880 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
20890 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f )] when it is no
208a0 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 longer required
208b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
208c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e te3_open_v2() in
208d0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 terface works li
208e0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ke sqlite3_open(
208f0 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ).** except that
20900 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 it accepts two
20910 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d additional param
20920 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 eters for additi
20930 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 onal control.**
20940 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 over the new dat
20950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20960 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 . ^(The flags p
20970 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 arameter to.** s
20980 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
20990 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 can take one of
209a0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e .** the followin
209b0 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 g three values,
209c0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 optionally combi
209d0 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a ned with the .**
209e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
209f0 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f MUTEX], [SQLITE_
20a00 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c OPEN_FULLMUTEX],
20a10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 [SQLITE_OPEN_SH
20a20 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b AREDCACHE],.** [
20a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
20a40 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f ATECACHE], and/o
20a50 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 r [SQLITE_OPEN_U
20a60 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a RI] flags:)^.**.
20a70 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 ** <dl>.** ^(<dt
20a80 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
20a90 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 ADONLY]</dt>.**
20aa0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
20ab0 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 is opened in re
20ac0 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 ad-only mode. I
20ad0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 f the database d
20ae0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 oes not.** alrea
20af0 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 dy exist, an err
20b00 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c or is returned.<
20b10 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c /dd>)^.**.** ^(<
20b20 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
20b30 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a READWRITE]</dt>.
20b40 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
20b50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f ase is opened fo
20b60 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 r reading and wr
20b70 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c iting if possibl
20b80 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a e, or reading.**
20b90 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c only if the fil
20ba0 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 e is write prote
20bb0 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 cted by the oper
20bc0 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 ating system. I
20bd0 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 n either.** case
20be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 the database mu
20bf0 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 st already exist
20c00 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 , otherwise an e
20c10 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
20c20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
20c30 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
20c40 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
20c50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
20c60 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
20c70 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
20c80 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
20c90 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 ng and writing,
20ca0 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 and is created i
20cb0 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 f.** it does not
20cc0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 already exist.
20cd0 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 This is the beha
20ce0 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 vior that is alw
20cf0 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 ays used for.**
20d00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
20d10 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nd sqlite3_open1
20d20 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 6().</dd>)^.** <
20d30 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 /dl>.**.** If th
20d40 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
20d50 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
20d60 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 v2() is not one
20d70 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e of the.** combin
20d80 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f ations shown abo
20d90 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f ve optionally co
20da0 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 mbined with othe
20db0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 r.** [SQLITE_OPE
20dc0 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c N_READONLY | SQL
20dd0 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d ITE_OPEN_* bits]
20de0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 .** then the beh
20df0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
20e00 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
20e10 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e e [SQLITE_OPEN_N
20e20 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 OMUTEX] flag is
20e30 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 set, then the da
20e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20e50 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 n.** opens in th
20e60 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b e multi-thread [
20e70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
20e80 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 as long as the s
20e90 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 ingle-thread.**
20ea0 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 mode has not bee
20eb0 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 n set at compile
20ec0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 -time or start-t
20ed0 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ime. ^If the.**
20ee0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
20ef0 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 LLMUTEX] flag is
20f00 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 set then the da
20f10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
20f20 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 n opens.** in th
20f30 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
20f40 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e reading mode] un
20f50 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 less single-thre
20f60 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f ad was.** previo
20f70 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 usly selected at
20f80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 compile-time or
20f90 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 start-time..**
20fa0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ^The [SQLITE_OPE
20fb0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 N_SHAREDCACHE] f
20fc0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 lag causes the d
20fd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20fe0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 on to be.** elig
20ff0 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 ible to use [sha
21000 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c red cache mode],
21010 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
21020 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 hether or not sh
21030 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 ared.** cache is
21040 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b enabled using [
21050 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 sqlite3_enable_s
21060 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 hared_cache()].
21070 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 ^The.** [SQLITE
21080 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
21090 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 HE] flag causes
210a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
210b0 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a nection to not.*
210c0 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e * participate in
210d0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d [shared cache m
210e0 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 ode] even if it
210f0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a is enabled..**.*
21100 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
21110 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
21120 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
21130 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a the name of the.
21140 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d ** [sqlite3_vfs]
21150 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 object that def
21160 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ines the operati
21170 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
21180 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ace that.** the
21190 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e new database con
211a0 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 nection should u
211b0 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 se. ^If the fou
211c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
211d0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
211e0 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 er then the defa
211f0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
21200 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 ] object is used
21210 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
21220 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 filename is ":me
21230 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 mory:", then a p
21240 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
21250 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 y in-memory data
21260 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 base.** is creat
21270 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 ed for the conne
21280 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e ction. ^This in
21290 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
212a0 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 will vanish whe
212b0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 n.** the databas
212c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
212d0 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 closed. Future
212e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
212f0 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 te might.** make
21300 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e use of addition
21310 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e al special filen
21320 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 ames that begin
21330 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 with the ":" cha
21340 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 racter..** It is
21350 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
21360 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 t when a databas
21370 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 e filename actua
21380 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 lly does begin w
21390 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 ith.** a ":" cha
213a0 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c racter you shoul
213b0 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c d prefix the fil
213c0 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 ename with a pat
213d0 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a hname such as.**
213e0 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 "./" to avoid a
213f0 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 mbiguity..**.**
21400 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ^If the filename
21410 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 is an empty str
21420 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 ing, then a priv
21430 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a ate, temporary.*
21440 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 * on-disk databa
21450 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 se will be creat
21460 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 ed. ^This priva
21470 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c te database will
21480 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 be.** automatic
21490 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 ally deleted as
214a0 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 soon as the data
214b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
214c0 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a is closed..**.**
214d0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 [[URI filenames
214e0 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e in sqlite3_open
214f0 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c ()]] <h3>URI Fil
21500 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a enames</h3>.**.*
21510 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e * ^If [URI filen
21520 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 ame] interpretat
21530 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 ion is enabled,
21540 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 and the filename
21550 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 argument.** beg
21560 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 ins with "file:"
21570 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e , then the filen
21580 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 ame is interpret
21590 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 ed as a URI. ^UR
215a0 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e I.** filename in
215b0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
215c0 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b enabled if the [
215d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
215e0 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 flag is.** set
215f0 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 in the fourth ar
21600 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
21610 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 3_open_v2(), or
21620 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 if it has.** bee
21630 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c n enabled global
21640 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 ly using the [SQ
21650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d LITE_CONFIG_URI]
21660 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 option with the
21670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
21680 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 fig()] method or
21690 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
216a0 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 USE_URI] compile
216b0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a -time option..**
216c0 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 As of SQLite ve
216d0 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 rsion 3.7.7, URI
216e0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 filename interp
216f0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e retation is turn
21700 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 ed off.** by def
21710 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 ault, but future
21720 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
21730 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 ite might enable
21740 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a URI filename.**
21750 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
21760 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 by default. See
21770 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 "[URI filenames
21780 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 ]" for additiona
21790 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e l.** information
217a0 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 ..**.** URI file
217b0 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 names are parsed
217c0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 according to RF
217d0 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 C 3986. ^If the
217e0 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a URI contains an.
217f0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 ** authority, th
21800 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 en it must be ei
21810 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 ther an empty st
21820 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 ring or the stri
21830 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 ng .** "localhos
21840 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 t". ^If the auth
21850 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 ority is not an
21860 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 empty string or
21870 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 "localhost", an
21880 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 .** error is ret
21890 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c urned to the cal
218a0 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 ler. ^The fragme
218b0 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 nt component of
218c0 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 a URI, if .** pr
218d0 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 esent, is ignore
218e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 d..**.** ^SQLite
218f0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 uses the path c
21900 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 omponent of the
21910 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 URI as the name
21920 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 of the disk file
21930 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 .** which contai
21940 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ns the database.
21950 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 ^If the path be
21960 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 gins with a '/'
21970 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 character, .** t
21980 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 hen it is interp
21990 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f reted as an abso
219a0 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 lute path. ^If t
219b0 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 he path does not
219c0 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 begin .** with
219d0 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 a '/' (meaning t
219e0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 hat the authorit
219f0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 y section is omi
21a00 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 tted from the UR
21a10 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 I).** then the p
21a20 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 ath is interpret
21a30 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 ed as a relative
21a40 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 path. .** ^On w
21a50 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 indows, the firs
21a60 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 t component of a
21a70 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 n absolute path
21a80 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 .** is a drive s
21a90 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e pecification (e.
21aa0 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 g. "C:")..**.**
21ab0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 [[core URI query
21ac0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a parameters]].**
21ad0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f The query compo
21ae0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 nent of a URI ma
21af0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 y contain parame
21b00 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e ters that are in
21b10 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 terpreted.** eit
21b20 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 her by SQLite it
21b30 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 self, or by a [V
21b40 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 FS | custom VFS
21b50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e implementation].
21b60 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
21b70 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 prets the follow
21b80 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79 20 ing three query
21b90 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a parameters:.**.*
21ba0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e * <ul>.** <li>
21bb0 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 <b>vfs</b>: ^Th
21bc0 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 e "vfs" paramete
21bd0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f r may be used to
21be0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d specify the nam
21bf0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 e of.** a VF
21c00 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 S object that pr
21c10 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 ovides the opera
21c20 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
21c30 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c rface that shoul
21c40 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 d.** be used
21c50 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
21c60 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 atabase file on
21c70 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f disk. ^If this o
21c80 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a ption is set to.
21c90 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 ** an empty
21ca0 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 string the defau
21cb0 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 lt VFS object is
21cc0 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 used. ^Specifyi
21cd0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a ng an unknown.**
21ce0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 VFS is an e
21cf0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 rror. ^If sqlite
21d00 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
21d10 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 sed and the vfs
21d20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
21d30 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 present, then t
21d40 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64 he VFS specified
21d50 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 by the option t
21d60 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 akes precedence
21d70 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 over.** the
21d80 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
21d90 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
21da0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
21db0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a open_v2()..**.**
21dc0 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c <li> <b>mode<
21dd0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 /b>: ^(The mode
21de0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
21df0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
21e00 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 ro", "rw",.**
21e10 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d "rwc", or "mem
21e20 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 ory". Attempting
21e30 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e to set it to an
21e40 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 y other value is
21e50 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 .** an error
21e60 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 )^. .** ^If
21e70 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 "ro" is specifie
21e80 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 d, then the data
21e90 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
21ea0 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a or read-only .**
21eb0 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 access, jus
21ec0 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c t as if the [SQL
21ed0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
21ee0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e Y] flag had been
21ef0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 set in the .**
21f00 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 third argume
21f10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
21f20 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 en_v2(). ^If the
21f30 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 mode option is
21f40 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 set to .** "
21f50 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 rw", then the da
21f60 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
21f70 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 for read-write
21f80 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 (but not create)
21f90 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c .** access,
21fa0 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 as if SQLITE_OP
21fb0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 EN_READWRITE (bu
21fc0 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 t not SQLITE_OPE
21fd0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a N_CREATE) had .*
21fe0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 * been set.
21ff0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 ^Value "rwc" is
22000 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
22010 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 tting both .**
22020 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 SQLITE_OPEN_R
22030 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c EADWRITE and SQL
22040 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e ITE_OPEN_CREATE.
22050 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f ^If the mode o
22060 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 ption is.**
22070 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 set to "memory"
22080 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d then a pure [in-
22090 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d memory database]
220a0 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 that never read
220b0 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 s.** or writ
220c0 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 es from disk is
220d0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 used. ^It is an
220e0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 error to specify
220f0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 a value for.**
22100 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 the mode par
22110 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c ameter that is l
22120 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20 ess restrictive
22130 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 than that specif
22140 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 ied by.** th
22150 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 e flags passed i
22160 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
22170 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
22180 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
22190 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 * <li> <b>cach
221a0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 e</b>: ^The cach
221b0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
221c0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 be set to either
221d0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 "shared" or.**
221e0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e "private". ^
221f0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 Setting it to "s
22200 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61 hared" is equiva
22210 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
22220 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 the.** SQLIT
22230 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
22240 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c HE bit in the fl
22250 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 ags argument pas
22260 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 sed to.** sq
22270 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
22280 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 ^Setting the ca
22290 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f che parameter to
222a0 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a "private" is .*
222b0 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 * equivalent
222c0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 to setting the
222d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
222e0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a ATECACHE bit..**
222f0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 ^If sqlite3
22300 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 _open_v2() is us
22310 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 ed and the "cach
22320 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 e" parameter is
22330 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 present in.**
22340 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 a URI filename
22350 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 , its value over
22360 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 rides any behavi
22370 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20 or requested by
22380 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 setting.** S
22390 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
223a0 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 TECACHE or SQLIT
223b0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
223c0 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c HE flag..** </ul
223d0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 >.**.** ^Specify
223e0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 ing an unknown p
223f0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 arameter in the
22400 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 query component
22410 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 of a URI is not
22420 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 an.** error. Fu
22430 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
22440 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e SQLite might un
22450 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f derstand additio
22460 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 nal query.** par
22470 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b ameters. See "[
22480 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
22490 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 with special me
224a0 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d aning to SQLite]
224b0 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f " for.** additio
224c0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
224d0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c .**.** [[URI fil
224e0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d ename examples]]
224f0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d <h3>URI filenam
22500 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a e examples</h3>.
22510 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 **.** <table bor
22520 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 der="1" align=ce
22530 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 nter cellpadding
22540 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 =5>.** <tr><th>
22550 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 URI filenames <t
22560 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 h> Results.** <t
22570 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 r><td> file:data
22580 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 .db <td> .**
22590 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 Open the f
225a0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e ile "data.db" in
225b0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 the current dir
225c0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c ectory..** <tr><
225d0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 td> file:/home/f
225e0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a red/data.db<br>.
225f0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
22600 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 :///home/fred/da
22610 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 ta.db <br> .**
22620 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c file://l
22630 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 ocalhost/home/fr
22640 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 ed/data.db <br>
22650 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 <td> .**
22660 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 Open the datab
22670 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f ase file "/home/
22680 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a fred/data.db"..*
22690 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
226a0 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f //darkstar/home/
226b0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 fred/data.db <td
226c0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 > .** A
226d0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 n error. "darkst
226e0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 ar" is not a rec
226f0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 ognized authorit
22700 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 y..** <tr><td st
22710 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 yle="white-space
22720 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 :nowrap"> .**
22730 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 file:///C
22740 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e :/Documents%20an
22750 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 d%20Settings/fre
22760 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 d/Desktop/data.d
22770 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 b.** <td> Wi
22780 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e ndows only: Open
22790 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e the file "data.
227a0 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 db" on fred's de
227b0 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a sktop on drive.*
227c0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e * C:. N
227d0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 ote that the %20
227e0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 escaping in thi
227f0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 s example is not
22800 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 strictly .**
22810 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 necessary
22820 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 - space charact
22830 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 ers can be used
22840 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 literally.**
22850 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c in URI fil
22860 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c enames..** <tr><
22870 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
22880 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 ?mode=ro&cache=p
22890 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 rivate <td> .**
228a0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 Open fi
228b0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 le "data.db" in
228c0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 the current dire
228d0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f ctory for read-o
228e0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 nly access..**
228f0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 Regardle
22900 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
22910 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 not shared-cach
22920 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 e mode is enable
22930 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 d by.**
22940 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 default, use a
22950 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a private cache..*
22960 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
22970 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
22980 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f db?vfs=unix-nolo
22990 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 ck <td>.**
229a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f Open file "/
229b0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
229c0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 b". Use the spec
229d0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f ial VFS "unix-no
229e0 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 lock"..** <tr><t
229f0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
22a00 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 mode=readonly <t
22a10 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
22a20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f An error. "reado
22a30 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 nly" is not a va
22a40 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 lid option for t
22a50 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 he "mode" parame
22a60 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e ter..** </table>
22a70 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 .**.** ^URI hexa
22a80 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
22a90 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 equences (%HH) a
22aa0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 re supported wit
22ab0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 hin the path and
22ac0 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e .** query compon
22ad0 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 ents of a URI. A
22ae0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
22af0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e ape sequence con
22b00 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 sists of a.** pe
22b10 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 rcent sign - "%"
22b20 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 - followed by e
22b30 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 xactly two hexad
22b40 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a ecimal digits .*
22b50 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 * specifying an
22b60 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 octet value. ^Be
22b70 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 fore the path or
22b80 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
22b90 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 s of a.** URI fi
22ba0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 lename are inter
22bb0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 preted, they are
22bc0 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
22bd0 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a TF-8 and all .**
22be0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
22bf0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 ape sequences re
22c00 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 placed by a sing
22c10 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 le byte containi
22c20 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 ng the.** corres
22c30 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 ponding octet. I
22c40 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 f this process g
22c50 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 enerates an inva
22c60 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 lid UTF-8 encodi
22c70 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c ng,.** the resul
22c80 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
22c90 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
22ca0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 to Windows users
22cb0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 :</b> The encod
22cc0 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 ing used for the
22cd0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
22ce0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 nt.** of sqlite3
22cf0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
22d00 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 te3_open_v2() mu
22d10 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 st be UTF-8, not
22d20 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 whatever.** cod
22d30 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 epage is current
22d40 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c ly defined. Fil
22d50 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e enames containin
22d60 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a g international.
22d70 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 ** characters mu
22d80 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
22d90 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 to UTF-8 prior t
22da0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 o passing them i
22db0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f nto.** sqlite3_o
22dc0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
22dd0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
22de0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
22df0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 dows Runtime use
22e00 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d rs:</b> The tem
22e10 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 porary directory
22e20 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 must be set.**
22e30 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
22e40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
22e50 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
22e60 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 v2(). Otherwise
22e70 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 , various.** fea
22e80 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 tures that requi
22e90 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 re the use of te
22ea0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 mporary files ma
22eb0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 y fail..**.** Se
22ec0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
22ed0 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d _temp_directory]
22ee0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
22ef0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 nt sqlite3_open(
22f00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 . const char *f
22f10 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
22f20 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
22f30 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c (UTF-8) */. sql
22f40 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
22f50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
22f60 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
22f70 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
22f80 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
22f90 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
22fa0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
22fb0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
22fc0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
22fd0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
22fe0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
22ff0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
23000 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
23010 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 I int sqlite3_op
23020 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 en_v2(. const c
23030 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
23040 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
23050 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
23060 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
23070 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b, /* OU
23080 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
23090 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 dle */. int fla
230a0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 gs,
230b0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 /* Flags */. c
230c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 onst char *zVfs
230d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
230e0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 f VFS module to
230f0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a use */.);../*.**
23100 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
23110 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 n Values For URI
23120 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a Parameters.**.*
23130 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c * These are util
23140 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 ity routines, us
23150 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c eful to VFS impl
23160 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 ementations, tha
23170 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 t check.** to se
23180 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 e if a database
23190 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 file was a URI t
231a0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 hat contained a
231b0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a specific query .
231c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e ** parameter, an
231d0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 d if so obtains
231e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 the value of tha
231f0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 t query paramete
23200 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 r..**.** If F is
23210 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
23220 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 lename pointer p
23230 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 assed into the x
23240 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 Open() method of
23250 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 .** a VFS imple
23260 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 mentation when t
23270 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
23280 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 er to xOpen() ha
23290 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 s one or .** mor
232a0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 e of the [SQLITE
232b0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 _OPEN_URI] or [S
232c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
232d0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 DB] bits set and
232e0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d .** P is the nam
232f0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 e of the query p
23300 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a arameter, then.*
23310 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 * sqlite3_uri_pa
23320 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
23330 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f urns the value o
23340 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d f the P.** param
23350 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 eter if it exist
23360 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s or a NULL poin
23370 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f ter if P does no
23380 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a t appear as a .*
23390 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 * query paramete
233a0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 r on F. If P is
233b0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 a query paramet
233c0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e er of F.** has n
233d0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 o explicit value
233e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 , then sqlite3_u
233f0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 ri_parameter(F,P
23400 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 ) returns.** a p
23410 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 ointer to an emp
23420 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ty string..**.**
23430 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
23440 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
23450 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 routine assumes
23460 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c that P is a bool
23470 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ean.** parameter
23480 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 and returns tru
23490 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 e (1) or false (
234a0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 0) according to
234b0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 the value.** of
234c0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f P. The sqlite3_
234d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
234e0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 B) routine retur
234f0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 ns true (1) if t
23500 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 he.** value of q
23510 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 uery parameter P
23520 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 is one of "yes"
23530 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e , "true", or "on
23540 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 " in any.** case
23550 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
23560 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e begins with a n
23570 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 on-zero number.
23580 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 The .** sqlite3
23590 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
235a0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ,B) routines ret
235b0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 urns false (0) i
235c0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a f the value of.*
235d0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 * query paramete
235e0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e r P is one of "n
235f0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 o", "false", or
23600 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 "off" in any cas
23610 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 e or.** if the v
23620 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 alue begins with
23630 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e a numeric zero.
23640 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 If P is not a
23650 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 query.** paramet
23660 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 er on F or if th
23670 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 e value of P is
23680 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 does not match a
23690 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f ny of the.** abo
236a0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ve, then sqlite3
236b0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
236c0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d ,B) returns (B!=
236d0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 0)..**.** The sq
236e0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 lite3_uri_int64(
236f0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 F,P,D) routine c
23700 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 onverts the valu
23710 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a e of P into a.**
23720 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
23730 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 nteger and retur
23740 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c ns that integer,
23750 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 or D if P does
23760 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 not.** exist. I
23770 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 f the value of P
23780 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 is something ot
23790 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 her than an inte
237a0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 ger, then.** zer
237b0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a o is returned..*
237c0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 * .** If F is a
237d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
237e0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 en sqlite3_uri_p
237f0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 arameter(F,P) re
23800 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a turns NULL and.*
23810 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
23820 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
23830 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 urns B. If F is
23840 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e not a NULL poin
23850 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f ter and.** is no
23860 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
23870 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 e pathname point
23880 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 er that SQLite p
23890 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 assed into the x
238a0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 Open.** VFS meth
238b0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 od, then the beh
238c0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f avior of this ro
238d0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e utine is undefin
238e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a ed and probably.
238f0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ** undesirable..
23900 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
23910 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
23920 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
23930 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
23940 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 ename, const cha
23950 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 r *zParam);.SQLI
23960 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
23970 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 e3_uri_boolean(c
23980 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
23990 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
239a0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 aram, int bDefau
239b0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 lt);.SQLITE_API
239c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
239d0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 lite3_uri_int64(
239e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e const char*, con
239f0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
23a00 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 3_int64);.../*.*
23a10 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f * CAPI3REF: Erro
23a20 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 r Codes And Mess
23a30 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ages.**.** ^The
23a40 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 sqlite3_errcode(
23a50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
23a60 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 rns the numeric
23a70 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 [result code] or
23a80 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
23a90 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
23aa0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 he most recent f
23ab0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 ailed sqlite3_*
23ac0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f API call.** asso
23ad0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 ciated with a [d
23ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23af0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 on]. If a prior
23b00 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a API call failed.
23b10 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 ** but the most
23b20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
23b30 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 succeeded, the r
23b40 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d eturn value from
23b50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 .** sqlite3_errc
23b60 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ode() is undefin
23b70 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ed. ^The sqlite
23b80 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
23b90 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 de().** interfac
23ba0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 e is the same ex
23bb0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 cept that it alw
23bc0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 ays returns the
23bd0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
23be0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 sult code] even
23bf0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 when extended re
23c00 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a sult codes are.*
23c10 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a * disabled..**.*
23c20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
23c30 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 rrmsg() and sqli
23c40 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 te3_errmsg16() r
23c50 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 eturn English-la
23c60 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 nguage.** text t
23c70 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
23c80 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 e error, as eith
23c90 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d er UTF-8 or UTF-
23ca0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 16 respectively.
23cb0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 .** ^(Memory to
23cc0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
23cd0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
23ce0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
23cf0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c lly..** The appl
23d00 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 ication does not
23d10 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 need to worry a
23d20 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 bout freeing the
23d30 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 result..** Howe
23d40 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 ver, the error s
23d50 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f tring might be o
23d60 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 verwritten or de
23d70 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 allocated by.**
23d80 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
23d90 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 to other SQLite
23da0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 interface funct
23db0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 ions.)^.**.** ^T
23dc0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 he sqlite3_errst
23dd0 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 r() interface re
23de0 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 turns the Englis
23df0 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a h-language text.
23e00 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 ** that describe
23e10 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f s the [result co
23e20 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a de], as UTF-8..*
23e30 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f * ^(Memory to ho
23e40 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 ld the error mes
23e50 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d sage string is m
23e60 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c anaged internall
23e70 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f y.** and must no
23e80 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 t be freed by th
23e90 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e e application)^.
23ea0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
23eb0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 serialized [thre
23ec0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 ading mode] is i
23ed0 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 n use, it might
23ee0 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 be the.** case t
23ef0 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 hat a second err
23f00 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 or occurs on a s
23f10 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 eparate thread i
23f20 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 n between.** the
23f30 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 time of the fir
23f40 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 st error and the
23f50 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 call to these i
23f60 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 nterfaces..** Wh
23f70 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c en that happens,
23f80 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f the second erro
23f90 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 r will be report
23fa0 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a ed since these.*
23fb0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 * interfaces alw
23fc0 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d ays report the m
23fd0 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c ost recent resul
23fe0 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 t. To avoid.**
23ff0 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 this, each threa
24000 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 d can obtain exc
24010 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 lusive use of th
24020 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
24030 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 ection] D.** by
24040 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 invoking [sqlite
24050 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 3_mutex_enter]([
24060 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 sqlite3_db_mutex
24070 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 ](D)) before beg
24080 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 inning.** to use
24090 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 D and invoking
240a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c [sqlite3_mutex_l
240b0 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 eave]([sqlite3_d
240c0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 b_mutex](D)) aft
240d0 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 er.** all calls
240e0 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 to the interface
240f0 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 s listed here ar
24100 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a e completed..**.
24110 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 ** If an interfa
24120 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 ce fails with SQ
24130 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 LITE_MISUSE, tha
24140 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 t means the inte
24150 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 rface.** was inv
24160 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 oked incorrectly
24170 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
24180 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 ion. In that ca
24190 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 se, the.** error
241a0 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 code and messag
241b0 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 e may or may not
241c0 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 be set..*/.SQLI
241d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
241e0 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 e3_errcode(sqlit
241f0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f e3 *db);.SQLITE_
24200 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
24210 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
24220 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 (sqlite3 *db);.S
24230 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
24240 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
24250 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a rmsg(sqlite3*);.
24260 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
24270 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 void *sqlite3_e
24280 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
24290 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
242a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
242b0 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 3_errstr(int);..
242c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
242d0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 SQL Statement Ob
242e0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
242f0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 : {prepared stat
24300 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 ement} {prepared
24310 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a statements}.**.
24320 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
24330 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 f this object re
24340 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c presents a singl
24350 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e e SQL statement.
24360 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
24370 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f is variously kno
24380 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 wn as a "prepare
24390 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 d statement" or
243a0 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 a.** "compiled S
243b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 QL statement" or
243c0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 simply as a "st
243d0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 atement"..**.**
243e0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 The life of a st
243f0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 atement object g
24400 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 oes something li
24410 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
24420 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 ol>.** <li> Crea
24430 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 te the object us
24440 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ing [sqlite3_pre
24450 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 pare_v2()] or a
24460 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 related.**
24470 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 function..** <li
24480 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f > Bind values to
24490 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 [host parameter
244a0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c s] using the sql
244b0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a ite3_bind_*().**
244c0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 interfaces
244d0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 ..** <li> Run th
244e0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 e SQL by calling
244f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
24500 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 ] one or more ti
24510 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 mes..** <li> Res
24520 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 et the statement
24530 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
24540 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f reset()] then go
24550 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f back.** to
24560 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 step 2. Do thi
24570 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 s zero or more t
24580 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 imes..** <li> De
24590 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 stroy the object
245a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
245b0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 finalize()]..**
245c0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 </ol>.**.** Refe
245d0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 r to documentati
245e0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c on on individual
245f0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 methods above f
24600 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
24610 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
24620 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
24630 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c sqlite3_stmt sql
24640 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a ite3_stmt;../*.*
24650 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
24660 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a time Limits.**.*
24670 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 * ^(This interfa
24680 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 ce allows the si
24690 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f ze of various co
246a0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c nstructs to be l
246b0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 imited.** on a c
246c0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e onnection by con
246d0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 nection basis.
246e0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
246f0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 ter is the.** [d
24700 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
24710 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 on] whose limit
24720 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 is to be set or
24730 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a queried. The.**
24740 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
24750 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 r is one of the
24760 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 [limit categorie
24770 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 s] that define a
24780 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e .** class of con
24790 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 structs to be si
247a0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 ze limited. The
247b0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
247c0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c is the.** new l
247d0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f imit for that co
247e0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a nstruct.)^.**.**
247f0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d ^If the new lim
24800 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 it is a negative
24810 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d number, the lim
24820 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e it is unchanged.
24830 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c .** ^(For each l
24840 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 imit category SQ
24850 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 LITE_LIMIT_<i>NA
24860 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 ME</i> there is
24870 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 a .** [limits |
24880 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
24890 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 ].** set at comp
248a0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 ile-time by a C
248b0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
248c0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 ro called.** [li
248d0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 mits | SQLITE_MA
248e0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a X_<i>NAME</i>]..
248f0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f ** (The "_LIMIT_
24900 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 " in the name is
24910 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 changed to "_MA
24920 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 X_".))^.** ^Atte
24930 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 mpts to increase
24940 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 a limit above i
24950 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f ts hard upper bo
24960 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e und are.** silen
24970 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f tly truncated to
24980 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 the hard upper
24990 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 bound..**.** ^Re
249a0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
249b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c her or not the l
249c0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 imit was changed
249d0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 , the .** [sqlit
249e0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 e3_limit()] inte
249f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
24a00 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 e prior value of
24a10 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e the limit..** ^
24a20 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 Hence, to find t
24a30 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
24a40 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 of a limit with
24a50 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c out changing it,
24a60 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b .** simply invok
24a70 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 e this interface
24a80 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 with the third
24a90 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f parameter set to
24aa0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 -1..**.** Run-t
24ab0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 ime limits are i
24ac0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
24ad0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 in applications
24ae0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 that manage.** b
24af0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e oth their own in
24b00 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 ternal database
24b10 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 and also databas
24b20 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 es that are cont
24b30 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 rolled.** by unt
24b40 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 rusted external
24b50 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 sources. An exa
24b60 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e mple application
24b70 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 might be a.** w
24b80 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 eb browser that
24b90 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 has its own data
24ba0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e bases for storin
24bb0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a g history and.**
24bc0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 separate databa
24bd0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 ses controlled b
24be0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 y JavaScript app
24bf0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f lications downlo
24c00 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 aded.** off the
24c10 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 Internet. The i
24c20 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
24c30 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 s can be given t
24c40 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 he.** large, def
24c50 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 ault limits. Da
24c60 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 tabases managed
24c70 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 by external sour
24c80 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 ces can.** be gi
24c90 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 ven much smaller
24ca0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 limits designed
24cb0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 to prevent a de
24cc0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a nial of service.
24cd0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 ** attack. Deve
24ce0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 lopers might als
24cf0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 o want to use th
24d00 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
24d10 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 uthorizer()].**
24d20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 interface to fur
24d30 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 ther control unt
24d40 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 rusted SQL. The
24d50 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 size of the dat
24d60 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 abase.** created
24d70 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 by an untrusted
24d80 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 script can be c
24d90 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 ontained using t
24da0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f he.** [max_page_
24db0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e count] [PRAGMA].
24dc0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 .**.** New run-t
24dd0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f ime limit catego
24de0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 ries may be adde
24df0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
24e00 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ases..*/.SQLITE_
24e10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
24e20 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 limit(sqlite3*,
24e30 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 int id, int newV
24e40 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 al);../*.** CAPI
24e50 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
24e60 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a imit Categories.
24e70 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 ** KEYWORDS: {li
24e80 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a mit category} {*
24e90 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
24ea0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
24eb0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 nstants define v
24ec0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e arious performan
24ed0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 ce limits.** tha
24ee0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 t can be lowered
24ef0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 at run-time usi
24f00 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
24f10 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e t()]..** The syn
24f20 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 opsis of the mea
24f30 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 nings of the var
24f40 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 ious limits is s
24f50 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 hown below..** A
24f60 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
24f70 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 ation is availab
24f80 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 le at [limits |
24f90 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 Limits in SQLite
24fa0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a ]..**.** <dl>.**
24fb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
24fc0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 LENGTH]] ^(<dt>S
24fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
24fe0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
24ff0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 he maximum size
25000 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 of any string or
25010 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 BLOB or table r
25020 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 ow, in bytes.<dd
25030 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
25040 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
25050 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 GTH]] ^(<dt>SQLI
25060 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
25070 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
25080 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
25090 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 th of an SQL sta
250a0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 tement, in bytes
250b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
250c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
250d0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LUMN]] ^(<dt>SQL
250e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
250f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
25100 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
25110 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
25120 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e table definition
25130 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 or in the.** re
25140 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
25150 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 ELECT] or the ma
25160 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
25170 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e columns in an in
25180 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 dex.** or in an
25190 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 ORDER BY or GROU
251a0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 P BY clause.</dd
251b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
251c0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
251d0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 PTH]] ^(<dt>SQLI
251e0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
251f0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e PTH</dt>.** <dd>
25200 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 The maximum dept
25210 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 h of the parse t
25220 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 ree on any expre
25230 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ssion.</dd>)^.**
25240 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
25250 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
25260 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 CT]] ^(<dt>SQLIT
25270 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
25280 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 _SELECT</dt>.**
25290 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
252a0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 number of terms
252b0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 in a compound SE
252c0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c LECT statement.<
252d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
252e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
252f0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 _OP]] ^(<dt>SQLI
25300 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
25310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
25320 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
25330 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 of instructions
25340 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 in a virtual mac
25350 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 hine program.**
25360 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
25370 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t an SQL stateme
25380 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 nt. This limit
25390 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
253a0 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 .** enforced, th
253b0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 ough that might
253c0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 be added in some
253d0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
253e0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 of.** SQLite.</d
253f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
25400 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 ITE_LIMIT_FUNCTI
25410 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 ON_ARG]] ^(<dt>S
25420 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
25430 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a TION_ARG</dt>.**
25440 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
25450 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
25460 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 ents on a functi
25470 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
25480 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
25490 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 ATTACHED]] ^(<dt
254a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 >SQLITE_LIMIT_AT
254b0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c TACHED</dt>.** <
254c0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
254d0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 umber of [ATTACH
254e0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 | attached data
254f0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a bases].)^</dd>.*
25500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
25510 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
25520 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c _LENGTH]].** ^(<
25530 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
25540 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
25550 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
25560 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
25570 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 th of the patter
25580 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 n argument to th
25590 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b e [LIKE] or.** [
255a0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e GLOB] operators.
255b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
255c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
255d0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a IABLE_NUMBER]].*
255e0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c * ^(<dt>SQLITE_L
255f0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
25600 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 MBER</dt>.** <dd
25610 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 >The maximum ind
25620 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 ex number of any
25630 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 [parameter] in
25640 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
25650 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 .)^.**.** [[SQLI
25660 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
25670 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 _DEPTH]] ^(<dt>S
25680 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 QLITE_LIMIT_TRIG
25690 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a GER_DEPTH</dt>.*
256a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
256b0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 m depth of recur
256c0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 sion for trigger
256d0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 s.</dd>)^.** </d
256e0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
256f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
25700 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 H
25710 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
25720 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f QLITE_LIMIT_SQL_
25730 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 LENGTH
25740 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
25750 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
25760 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 UMN
25770 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 2.#define
25780 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 SQLITE_LIMIT_EX
25790 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 PR_DEPTH
257a0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 3.#defin
257b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 e SQLITE_LIMIT_C
257c0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 OMPOUND_SELECT
257d0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 4.#defi
257e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
257f0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 VDBE_OP
25800 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 5.#def
25810 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
25820 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 _FUNCTION_ARG
25830 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
25840 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
25850 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 T_ATTACHED
25860 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 7.#d
25870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
25880 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
25890 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 LENGTH 8.#
258a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
258b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
258c0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a BER 9.
258d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
258e0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
258f0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 TH 10
25900 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
25910 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 : Compiling An S
25920 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 QL Statement.**
25930 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 KEYWORDS: {SQL s
25940 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 tatement compile
25950 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 r}.**.** To exec
25960 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 ute an SQL query
25970 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 , it must first
25980 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f be compiled into
25990 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 a byte-code.**
259a0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e program using on
259b0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
259c0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 nes..**.** The f
259d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 irst argument, "
259e0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 db", is a [datab
259f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
25a00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a obtained from a.
25a10 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 ** prior success
25a20 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ful call to [sql
25a30 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
25a40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
25a50 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ] or.** [sqlite3
25a60 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 _open16()]. The
25a70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25a80 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 tion must not ha
25a90 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a ve been closed..
25aa0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
25ab0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c argument, "zSql
25ac0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d ", is the statem
25ad0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c ent to be compil
25ae0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 ed, encoded.** a
25af0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f s either UTF-8 o
25b00 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 r UTF-16. The s
25b10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
25b20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
25b30 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 pare_v2().** int
25b40 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d erfaces use UTF-
25b50 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 8, and sqlite3_p
25b60 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 repare16() and s
25b70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
25b80 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 _v2().** use UTF
25b90 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 -16..**.** ^If t
25ba0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e he nByte argumen
25bb0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a t is less than z
25bc0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 ero, then zSql i
25bd0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 s read up to the
25be0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 .** first zero t
25bf0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e erminator. ^If n
25c00 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 Byte is non-nega
25c10 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 tive, then it is
25c20 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 the maximum.**
25c30 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 number of bytes
25c40 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e read from zSql.
25c50 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 ^When nByte is
25c60 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 non-negative, t
25c70 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e he.** zSql strin
25c80 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 g ends at either
25c90 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 the first '\000
25ca0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 ' or '\u0000' ch
25cb0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 aracter or.** th
25cc0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c e nByte-th byte,
25cd0 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 whichever comes
25ce0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 first. If the c
25cf0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 aller knows.** t
25d00 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 hat the supplied
25d10 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 string is nul-t
25d20 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 erminated, then
25d30 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c there is a small
25d40 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 .** performance
25d50 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 advantage to be
25d60 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e gained by passin
25d70 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d g an nByte param
25d80 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 eter that.** is
25d90 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d equal to the num
25da0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
25db0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
25dc0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 <i>including</i
25dd0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 >.** the nul-ter
25de0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 minator bytes as
25df0 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 this saves SQLi
25e00 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 te from having t
25e10 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 o.** make a copy
25e20 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 of the input st
25e30 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ring..**.** ^If
25e40 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
25e50 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 LL then *pzTail
25e60 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
25e70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
25e80 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 te.** past the e
25e90 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
25ea0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
25eb0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
25ec0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 utines only.** c
25ed0 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
25ee0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
25ef0 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
25f00 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
25f10 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 to.** what remai
25f20 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ns uncompiled..*
25f30 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 *.** ^*ppStmt is
25f40 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
25f50 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
25f60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25f70 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
25f80 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
25f90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
25fa0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 . ^If there is
25fb0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d an error, *ppStm
25fc0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e t is set.** to N
25fd0 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e ULL. ^If the in
25fe0 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
25ff0 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
26000 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
26010 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
26020 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
26030 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
26040 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
26050 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
26060 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
26070 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
26080 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
26090 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
260a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
260b0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
260c0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
260d0 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
260e0 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
260f0 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 **.** ^On succes
26100 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 s, the sqlite3_p
26110 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 repare() family
26120 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 of routines retu
26130 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a rn [SQLITE_OK];.
26140 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
26150 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
26160 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
26170 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
26180 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c are_v2() and sql
26190 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
261a0 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 2() interfaces a
261b0 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 re.** recommende
261c0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 d for all new pr
261d0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 ograms. The two
261e0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 older interfaces
261f0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a are retained.**
26200 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
26210 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 ompatibility, bu
26220 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 t their use is d
26230 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e iscouraged..** ^
26240 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 In the "v2" inte
26250 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 rfaces, the prep
26260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a ared statement.*
26270 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e * that is return
26280 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
26290 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 _stmt] object) c
262a0 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f ontains a copy o
262b0 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 f the.** origina
262c0 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 l SQL text. This
262d0 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c causes the [sql
262e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 ite3_step()] int
262f0 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 erface to.** beh
26300 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 ave differently
26310 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a in three ways:.*
26320 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
26330 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 >.** ^If the dat
26340 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 abase schema cha
26350 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 nges, instead of
26360 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 returning [SQLI
26370 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 TE_SCHEMA] as it
26380 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 .** always used
26390 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f to do, [sqlite3_
263a0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 step()] will aut
263b0 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d omatically recom
263c0 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 pile the SQL.**
263d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 statement and tr
263e0 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 y to run it agai
263f0 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 n. As many as [S
26400 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 QLITE_MAX_SCHEMA
26410 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 _RETRY].** retri
26420 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 es will occur be
26430 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 fore sqlite3_ste
26440 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 p() gives up and
26450 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f returns an erro
26460 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a r..** </li>.**.*
26470 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 * <li>.** ^When
26480 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c an error occurs,
26490 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
264a0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e ] will return on
264b0 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 e of the detaile
264c0 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 d.** [error code
264d0 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 s] or [extended
264e0 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e error codes]. ^
264f0 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 The legacy behav
26500 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 ior was that.**
26510 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
26520 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 would only retu
26530 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 rn a generic [SQ
26540 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 LITE_ERROR] resu
26550 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 lt code.** and t
26560 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 he application w
26570 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b ould have to mak
26580 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 e a second call
26590 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 to [sqlite3_rese
265a0 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 t()].** in order
265b0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 to find the und
265c0 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 erlying cause of
265d0 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 the problem. Wi
265e0 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 th the "v2" prep
265f0 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 are.** interface
26600 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e s, the underlyin
26610 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 g reason for the
26620 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
26630 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a ed immediately..
26640 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c ** </li>.**.** <
26650 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 li>.** ^If the s
26660 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f pecific value bo
26670 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 und to [paramete
26680 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 r | host paramet
26690 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 er] in the .** W
266a0 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 HERE clause migh
266b0 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 t influence the
266c0 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 choice of query
266d0 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 plan for a state
266e0 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 ment,.** then th
266f0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c e statement will
26700 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c be automaticall
26710 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 y recompiled, as
26720 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 if there had be
26730 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 en .** a schema
26740 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 change, on the f
26750 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 irst [sqlite3_s
26760 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c tep()] call foll
26770 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 owing any change
26780 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
26790 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 te3_bind_text |
267a0 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 bindings] of tha
267b0 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a t [parameter]. .
267c0 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 ** ^The specific
267d0 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d value of WHERE-
267e0 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 clause [paramete
267f0 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e r] might influen
26800 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 ce the .** choic
26810 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 e of query plan
26820 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 if the parameter
26830 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e is the left-han
26840 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b d side of a [LIK
26850 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 E].** or [GLOB]
26860 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 operator or if t
26870 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
26880 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 compared to an i
26890 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a ndexed column.**
268a0 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 and the [SQLITE
268b0 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 _ENABLE_STAT3] c
268c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
268d0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a on is enabled..*
268e0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e * </li>.** </ol>
268f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
26900 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
26910 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 re(. sqlite3 *d
26920 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
26930 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
26940 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
26950 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
26960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
26970 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
26980 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
26990 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
269a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
269b0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
269c0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
269d0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
269e0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
269f0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
26a00 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 char **pzTail
26a10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
26a20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
26a30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
26a40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
26a50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
26a60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
26a70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
26a80 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
26a90 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
26aa0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f r *zSql, /
26ab0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
26ac0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a UTF-8 encoded *
26ad0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
26ae0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
26af0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
26b00 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
26b10 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
26b20 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
26b30 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
26b40 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
26b50 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 char **pzTail
26b60 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
26b70 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
26b80 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
26b90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
26ba0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
26bb0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a e16(. sqlite3 *
26bc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f db, /
26bd0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c * Database handl
26be0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 e */. const voi
26bf0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f d *zSql, /
26c00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c * SQL statement,
26c10 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 UTF-16 encoded
26c20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
26c30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
26c40 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
26c50 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
26c60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
26c70 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
26c80 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
26c90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
26ca0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 t void **pzTail
26cb0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
26cc0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
26cd0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
26ce0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
26cf0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nt sqlite3_prepa
26d00 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 re16_v2(. sqlit
26d10 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
26d20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
26d30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
26d40 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 void *zSql,
26d50 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
26d60 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f ent, UTF-16 enco
26d70 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
26d80 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
26d90 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
26da0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
26db0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
26dc0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
26dd0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
26de0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
26df0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
26e00 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
26e10 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
26e20 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
26e30 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
26e40 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
26e50 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
26e60 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e L.**.** ^This in
26e70 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
26e80 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 sed to retrieve
26e90 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 a saved copy of
26ea0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 the original.**
26eb0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f SQL text used to
26ec0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 create a [prepa
26ed0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 red statement] i
26ee0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 f that statement
26ef0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 was.** compiled
26f00 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 using either [s
26f10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
26f20 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 2()] or [sqlite3
26f30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
26f40 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
26f50 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
26f60 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f te3_sql(sqlite3_
26f70 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
26f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
26f90 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
26fa0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 QL Statement Wri
26fb0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 tes The Database
26fc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
26fd0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
26fe0 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 y(X) interface r
26ff0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e eturns true (non
27000 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 -zero) if.** and
27010 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 only if the [pr
27020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27030 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 ] X makes no dir
27040 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a ect changes to.*
27050 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
27060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
27070 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 le..**.** Note t
27080 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e hat [application
27090 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
270a0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 ctions] or.** [v
270b0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d irtual tables] m
270c0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
270d0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 database indirec
270e0 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 tly as a side ef
270f0 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 fect. .** ^(For
27100 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 example, if an
27110 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
27120 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 nes a function "
27130 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a eval()" that .**
27140 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f calls [sqlite3_
27150 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 exec()], then th
27160 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 e following SQL
27170 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a statement would.
27180 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ** change the da
27190 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f tabase file thro
271a0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 ugh side-effects
271b0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
271c0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
271d0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c SELECT eval('DEL
271e0 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 ETE FROM t1') FR
271f0 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e OM t2;.** </pre>
27200 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
27210 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 .** But because
27220 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
27230 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
27240 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
27250 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 ase file.** dire
27260 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 ctly, sqlite3_st
27270 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f mt_readonly() wo
27280 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e uld still return
27290 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e true.)^.**.** ^
272a0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 Transaction cont
272b0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 rol statements s
272c0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 uch as [BEGIN],
272d0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 [COMMIT], [ROLLB
272e0 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f ACK],.** [SAVEPO
272f0 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 INT], and [RELEA
27300 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 SE] cause sqlite
27310 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
27320 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 ) to return true
27330 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 ,.** since the s
27340 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 tatements themse
27350 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 lves do not actu
27360 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 ally modify the
27370 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 database but.**
27380 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 rather they cont
27390 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f rol the timing o
273a0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 f when other sta
273b0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 tements modify t
273c0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e he .** database.
273d0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 ^The [ATTACH]
273e0 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 and [DETACH] sta
273f0 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 tements also cau
27400 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 se.** sqlite3_st
27410 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
27420 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e return true sin
27430 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 ce, while those
27440 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 statements.** ch
27450 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 ange the configu
27460 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 ration of a data
27470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
27480 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b they do not mak
27490 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f e .** changes to
274a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
274b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
274c0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 es on disk..*/.S
274d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
274e0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f lite3_stmt_reado
274f0 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 nly(sqlite3_stmt
27500 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
27510 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
27520 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 mine If A Prepar
27530 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 ed Statement Has
27540 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a Been Reset.**.*
27550 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
27560 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 tmt_busy(S) inte
27570 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
27580 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
27590 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
275a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 d statement] S h
275b0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 as been stepped
275c0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 at least once us
275d0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
275e0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 _step(S)] but ha
275f0 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d s not run to com
27600 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 pletion and/or h
27610 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 as not .** been
27620 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c reset using [sql
27630 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 ite3_reset(S)].
27640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 ^The sqlite3_st
27650 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e mt_busy(S).** in
27660 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
27670 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 false if S is a
27680 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 NULL pointer. I
27690 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a f S is not a .**
276a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e NULL pointer an
276b0 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 d is not a point
276c0 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 er to a valid [p
276d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
276e0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 t].** object, th
276f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
27700 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 is undefined and
27710 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 probably undesi
27720 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 rable..**.** Thi
27730 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 s interface can
27740 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 be used in combi
27750 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f nation [sqlite3_
27760 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 next_stmt()].**
27770 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 to locate all pr
27780 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27790 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
277a0 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a h a database .**
277b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
277c0 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 are in need of
277d0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 being reset. Th
277e0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a is can be used,.
277f0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ** for example,
27800 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f in diagnostic ro
27810 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 utines to search
27820 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a for prepared .*
27830 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 * statements tha
27840 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 t are holding a
27850 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e transaction open
27860 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
27870 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 int sqlite3_stmt
27880 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 _busy(sqlite3_st
27890 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
278a0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c I3REF: Dynamical
278b0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f ly Typed Value O
278c0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
278d0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 S: {protected sq
278e0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e lite3_value} {un
278f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
27900 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 3_value}.**.** S
27910 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 QLite uses the s
27920 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
27930 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ect to represent
27940 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 all values.** t
27950 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 hat can be store
27960 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 d in a database
27970 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 table. SQLite us
27980 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e es dynamic typin
27990 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c g.** for the val
279a0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 ues it stores.
279b0 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 ^Values stored i
279c0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 n sqlite3_value
279d0 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 objects.** can b
279e0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 e integers, floa
279f0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
27a00 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 s, strings, BLOB
27a10 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a s, or NULL..**.*
27a20 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c * An sqlite3_val
27a30 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 ue object may be
27a40 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 either "protect
27a50 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 ed" or "unprotec
27a60 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e ted"..** Some in
27a70 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
27a80 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
27a90 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 ite3_value. Oth
27aa0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a er interfaces.**
27ab0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 will accept eit
27ac0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 her a protected
27ad0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
27ae0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
27af0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 .** Every interf
27b00 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 ace that accepts
27b10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 sqlite3_value a
27b20 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 rguments specifi
27b30 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 es.** whether or
27b40 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 not it requires
27b50 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c a protected sql
27b60 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a ite3_value..**.*
27b70 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f * The terms "pro
27b80 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 tected" and "unp
27b90 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 rotected" refer
27ba0 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f to whether or no
27bb0 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 t.** a mutex is
27bc0 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e held. An intern
27bd0 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 al mutex is held
27be0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 for a protected
27bf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
27c00 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 e object but no
27c10 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f mutex is held fo
27c20 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
27c30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
27c40 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 e object. If SQ
27c50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
27c60 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 to be single-th
27c70 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 readed.** (with
27c80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
27c90 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b FE=0] and with [
27ca0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
27cb0 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 fe()] returning
27cc0 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 0).** or if SQLi
27cd0 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 te is run in one
27ce0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 of reduced mute
27cf0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c x modes .** [SQL
27d00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
27d10 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c ETHREAD] or [SQL
27d20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
27d30 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 THREAD].** then
27d40 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 there is no dist
27d50 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 inction between
27d60 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e protected and un
27d70 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c protected.** sql
27d80 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
27d90 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 ts and they can
27da0 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 be used intercha
27db0 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 ngeably. Howeve
27dc0 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 r,.** for maximu
27dd0 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 m code portabili
27de0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 ty it is recomme
27df0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 nded that applic
27e00 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 ations.** still
27e10 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 make the distinc
27e20 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f tion between pro
27e30 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f tected and unpro
27e40 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 tected.** sqlite
27e50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
27e60 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 even when not st
27e70 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e rictly required.
27e80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
27e90 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
27ea0 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 s that are passe
27eb0 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 d as parameters
27ec0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c into the.** impl
27ed0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 ementation of [a
27ee0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
27ef0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
27f00 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e ] are protected.
27f10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27f20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 _value object re
27f30 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
27f40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c lite3_column_val
27f50 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 ue()] is unprote
27f60 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 cted..** Unprote
27f70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
27f80 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f ue objects may o
27f90 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 nly be used with
27fa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
27fb0 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 ult_value()] and
27fc0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
27fd0 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 alue()]..** The
27fe0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
27ff0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 lob | sqlite3_va
28000 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 lue_type()] fami
28010 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 ly of.** interfa
28020 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 ces require prot
28030 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
28040 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a lue objects..*/.
28050 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d typedef struct M
28060 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 em sqlite3_value
28070 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28080 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 F: SQL Function
28090 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a Context Object.*
280a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 *.** The context
280b0 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c in which an SQL
280c0 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 function execut
280d0 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 es is stored in
280e0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f an.** sqlite3_co
280f0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e ntext object. ^
28100 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
28110 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
28120 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 object.** is alw
28130 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 ays first parame
28140 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 ter to [applicat
28150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
28160 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 functions]..** T
28170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
28180 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
28190 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ion implementati
281a0 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 on will pass thi
281b0 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 s.** pointer thr
281c0 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 ough into calls
281d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 to [sqlite3_resu
281e0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 lt_int | sqlite3
281f0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b _result()],.** [
28200 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 sqlite3_aggregat
28210 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 e_context()], [s
28220 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 qlite3_user_data
28230 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
28240 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 _context_db_hand
28250 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f le()], [sqlite3_
28260 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a get_auxdata()],.
28270 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 ** and/or [sqlit
28280 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
28290 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 ]..*/.typedef st
282a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e ruct sqlite3_con
282b0 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e text sqlite3_con
282c0 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 text;../*.** CAP
282d0 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 I3REF: Binding V
282e0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 alues To Prepare
282f0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 d Statements.**
28300 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 KEYWORDS: {host
28310 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 parameter} {host
28320 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f parameters} {ho
28330 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d st parameter nam
28340 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 e}.** KEYWORDS:
28350 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 {SQL parameter}
28360 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d {SQL parameters}
28370 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 {parameter bind
28380 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 ing}.**.** ^(In
28390 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
283a0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 t text input to
283b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
283c0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 _v2()] and its v
283d0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 ariants,.** lite
283e0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c rals may be repl
283f0 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d aced by a [param
28400 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 eter] that match
28410 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 es one of follow
28420 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 ing.** templates
28430 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
28440 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 <li> ?.** <li>
28450 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a ?NNN.** <li> :
28460 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 VVV.** <li> @VV
28470 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a V.** <li> $VVV.
28480 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
28490 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 n the templates
284a0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 above, NNN repre
284b0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 sents an integer
284c0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 literal,.** and
284d0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 VVV represents
284e0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 an alphanumeric
284f0 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e identifier.)^ ^
28500 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
28510 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
28520 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
28530 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
28540 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
28550 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
28560 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
28570 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
28580 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
28590 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
285a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
285b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
285c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
285d0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a tines is always.
285e0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
285f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
28600 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e t] object return
28610 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 ed from.** [sqli
28620 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
28630 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
28640 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 s..**.** ^The se
28650 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
28660 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
28670 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 e SQL parameter
28680 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 to be set..** ^T
28690 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 he leftmost SQL
286a0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
286b0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 index of 1. ^W
286c0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d hen the same nam
286d0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 ed.** SQL parame
286e0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 ter is used more
286f0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f than once, seco
28700 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
28710 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 t.** occurrences
28720 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 have the same i
28730 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 ndex as the firs
28740 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a t occurrence..**
28750 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 ^The index for
28760 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
28770 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
28780 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
28790 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
287a0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
287b0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
287c0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 ^The index.** f
287d0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 or "?NNN" parame
287e0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 ters is the valu
287f0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 e of NNN..** ^Th
28800 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 e NNN value must
28810 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e be between 1 an
28820 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c d the [sqlite3_l
28830 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d imit()].** param
28840 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d eter [SQLITE_LIM
28850 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
28860 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c ER] (default val
28870 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 ue: 999)..**.**
28880 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
28890 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 ent is the value
288a0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 to bind to the
288b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 parameter..** ^I
288c0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
288d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
288e0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 _bind_text() or
288f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
28900 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 t16().** or sqli
28910 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 te3_bind_blob()
28920 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
28930 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 r then the fourt
28940 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 h parameter.** i
28950 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 s ignored and th
28960 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 e end result is
28970 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 the same as sqli
28980 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e te3_bind_null().
28990 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 .**.** ^(In thos
289a0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
289b0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
289c0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
289d0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
289e0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
289f0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
28a00 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
28a10 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
28a20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
28a30 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
28a40 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
28a50 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
28a60 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 s.)^.** ^If the
28a70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
28a80 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
28a90 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
28aa0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
28ab0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
28ac0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 then the length
28ad0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 of the string i
28ae0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
28af0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 of bytes up to t
28b00 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
28b10 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 rminator..** If
28b20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
28b30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
28b40 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e bind_blob() is n
28b50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a egative, then.**
28b60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
28b70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 undefined..** I
28b80 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 f a non-negative
28b90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
28ba0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f r is provided to
28bb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
28bc0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 xt().** or sqlit
28bd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
28be0 20 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d then that param
28bf0 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 eter must be the
28c00 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 byte offset.**
28c10 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 where the NUL te
28c20 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f rminator would o
28c30 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 ccur assuming th
28c40 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 e string were NU
28c50 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e L.** terminated.
28c60 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 If any NUL cha
28c70 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 racters occur at
28c80 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 byte offsets le
28c90 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 ss than .** the
28ca0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 value of the fou
28cb0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 rth parameter th
28cc0 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 en the resulting
28cd0 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 string value wi
28ce0 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d ll.** contain em
28cf0 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 bedded NULs. Th
28d00 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 e result of expr
28d10 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e essions involvin
28d20 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 g strings.** wit
28d30 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 h embedded NULs
28d40 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
28d50 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 .** ^The fifth a
28d60 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
28d70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 e3_bind_blob(),
28d80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
28d90 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 t(), and.** sqli
28da0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
28db0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f ) is a destructo
28dc0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
28dd0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
28de0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
28df0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
28e00 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e shed with it. ^
28e10 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
28e20 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 s called.** to d
28e30 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
28e40 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 OB or string eve
28e50 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f n if the call to
28e60 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
28e70 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 ob(),.** sqlite3
28e80 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 _bind_text(), or
28e90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
28ea0 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a xt16() fails. .
28eb0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 ** ^If the fifth
28ec0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
28ed0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 the special valu
28ee0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 e [SQLITE_STATIC
28ef0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 ], then SQLite a
28f00 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
28f10 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
28f20 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d s in static, unm
28f30 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 anaged space and
28f40 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
28f50 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e o be freed..** ^
28f60 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
28f70 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 ument has the va
28f80 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e lue [SQLITE_TRAN
28f90 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 SIENT], then.**
28fa0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 SQLite makes its
28fb0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
28fc0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d y of the data im
28fd0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 mediately, befor
28fe0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 e.** the sqlite3
28ff0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
29000 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a e returns..**.**
29010 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
29020 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f nd_zeroblob() ro
29030 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c utine binds a BL
29040 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 OB of length N t
29050 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 hat.** is filled
29060 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e with zeroes. ^
29070 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 A zeroblob uses
29080 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f a fixed amount o
29090 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 f memory.** (jus
290a0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 t an integer to
290b0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 hold its size) w
290c0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 hile it is being
290d0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a processed..** Z
290e0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 eroblobs are int
290f0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 ended to serve a
29100 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 s placeholders f
29110 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a or BLOBs whose.*
29120 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 * content is lat
29130 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 er written using
29140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
29150 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 b_open | increme
29160 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 ntal BLOB I/O] r
29170 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e outines..** ^A n
29180 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f egative value fo
29190 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 r the zeroblob r
291a0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f esults in a zero
291b0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a -length BLOB..**
291c0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 .** ^If any of t
291d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
291e0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 *() routines are
291f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e called with a N
29200 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 ULL pointer.** f
29210 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 or the [prepared
29220 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 statement] or w
29230 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 ith a prepared s
29240 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 tatement for whi
29250 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 ch.** [sqlite3_s
29260 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 tep()] has been
29270 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 called more rece
29280 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 ntly than [sqlit
29290 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 e3_reset()],.**
292a0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 then the call wi
292b0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
292c0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 E_MISUSE]. If a
292d0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f ny sqlite3_bind_
292e0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 ().** routine is
292f0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 passed a [prepa
29300 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
29310 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e hat has been fin
29320 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 alized, the.** r
29330 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
29340 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 ed and probably
29350 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e harmful..**.** ^
29360 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 Bindings are not
29370 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 cleared by the
29380 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
29390 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 ] routine..** ^U
293a0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 nbound parameter
293b0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
293c0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a d as NULL..**.**
293d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 ^The sqlite3_bi
293e0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 nd_* routines re
293f0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d turn [SQLITE_OK]
29400 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 on success or a
29410 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 n.** [error code
29420 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f ] if anything go
29430 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 es wrong..** ^[S
29440 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 QLITE_RANGE] is
29450 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
29460 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 parameter.** ind
29470 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
29480 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f ge. ^[SQLITE_NO
29490 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 MEM] is returned
294a0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 if malloc() fai
294b0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c ls..**.** See al
294c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
294d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
294e0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
294f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
29500 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 _name()], and [s
29510 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
29520 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
29530 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
29540 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
29550 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
29560 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
29570 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 id*, int n, void
29580 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
29590 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
295a0 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 te3_bind_double(
295b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
295c0 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c nt, double);.SQL
295d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
295e0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c te3_bind_int(sql
295f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
29600 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
29610 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
29620 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 nd_int64(sqlite3
29630 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
29640 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c ite3_int64);.SQL
29650 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
29660 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 te3_bind_null(sq
29670 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
29680 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
29690 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 t sqlite3_bind_t
296a0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
296b0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 *, int, const ch
296c0 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 ar*, int n, void
296d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c (*)(void*));.SQL
296e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
296f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
29700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
29710 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c nt, const void*,
29720 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f int, void(*)(vo
29730 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
29740 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
29750 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 nd_value(sqlite3
29760 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
29770 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 st sqlite3_value
29780 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
29790 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
297a0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 zeroblob(sqlite3
297b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
297c0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
297d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
297e0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a SQL Parameters.*
297f0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
29800 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ne can be used t
29810 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 o find the numbe
29820 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 r of [SQL parame
29830 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 ters].** in a [p
29840 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29850 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 t]. SQL paramet
29860 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f ers are tokens o
29870 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f f the.** form "?
29880 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 ", "?NNN", ":AAA
29890 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 ", "$AAA", or "@
298a0 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 AAA" that serve
298b0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 as.** placeholde
298c0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 rs for values th
298d0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f at are [sqlite3_
298e0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e bind_blob | boun
298f0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 d].** to the par
29900 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 ameters at a lat
29910 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e er time..**.** ^
29920 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 (This routine ac
29930 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 tually returns t
29940 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
29950 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f largest (rightmo
29960 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 st).** parameter
29970 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 . For all forms
29980 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 except ?NNN, thi
29990 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e s will correspon
299a0 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 d to the.** numb
299b0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 er of unique par
299c0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 ameters. If par
299d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f ameters of the ?
299e0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 NNN form are use
299f0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 d,.** there may
29a00 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c be gaps in the l
29a10 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 ist.)^.**.** See
29a20 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
29a30 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
29a40 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 3_bind()],.** [s
29a50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
29a60 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 meter_name()], a
29a70 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 nd.** [sqlite3_b
29a80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
29a90 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 dex()]..*/.SQLIT
29aa0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
29ab0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
29ac0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 _count(sqlite3_s
29ad0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
29ae0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
29af0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 A Host Parameter
29b00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
29b10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
29b20 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 er_name(P,N) int
29b30 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a erface returns.*
29b40 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 * the name of th
29b50 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 e N-th [SQL para
29b60 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 meter] in the [p
29b70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
29b80 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 t] P..** ^(SQL p
29b90 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
29ba0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 form "?NNN" or
29bb0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 ":AAA" or "@AAA"
29bc0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 or "$AAA".** ha
29bd0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 ve a name which
29be0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f is the string "?
29bf0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f NNN" or ":AAA" o
29c00 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 r "@AAA" or "$AA
29c10 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 A".** respective
29c20 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 ly..** In other
29c30 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 words, the initi
29c40 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 al ":" or "$" or
29c50 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 "@" or "?".** i
29c60 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 s included as pa
29c70 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 rt of the name.)
29c80 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 ^.** ^Parameters
29c90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 of the form "?"
29ca0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f without a follo
29cb0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 wing integer hav
29cc0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 e no name.** and
29cd0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f are referred to
29ce0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f as "nameless" o
29cf0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 r "anonymous par
29d00 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 ameters"..**.**
29d10 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 ^The first host
29d20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
29d30 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 index of 1, not
29d40 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 0..**.** ^If th
29d50 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 e value N is out
29d60 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 of range or if
29d70 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 the N-th paramet
29d80 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 er is.** nameles
29d90 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 s, then NULL is
29da0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 returned. ^The
29db0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
29dc0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 is.** always in
29dd0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 UTF-8 encoding e
29de0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 ven if the named
29df0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a parameter was.*
29e00 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 * originally spe
29e10 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 cified as UTF-16
29e20 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 in [sqlite3_pre
29e30 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 pare16()] or.**
29e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
29e50 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 16_v2()]..**.**
29e60 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
29e70 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
29e80 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a ite3_bind()],.**
29e90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
29ea0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 arameter_count()
29eb0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
29ec0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
29ed0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 r_index()]..*/.S
29ee0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
29ef0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 char *sqlite3_bi
29f00 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
29f10 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
29f20 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
29f30 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
29f40 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
29f50 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a h A Given Name.*
29f60 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
29f70 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
29f80 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
29f90 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
29fa0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
29fb0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
29fc0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
29fd0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
29fe0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
29ff0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2a000 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
2a010 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
2a020 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
2a030 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
2a040 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
2a050 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
2a060 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
2a070 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
2a080 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
2a090 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
2a0a0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
2a0b0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
2a0c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a0d0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
2a0e0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2a0f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2a100 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
2a110 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2a120 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2a130 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2a140 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2a150 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
2a160 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2a170 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2a180 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 ter_index(sqlite
2a190 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 3_stmt*, const c
2a1a0 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a har *zName);../*
2a1b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
2a1c0 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 set All Bindings
2a1d0 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 On A Prepared S
2a1e0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e tatement.**.** ^
2a1f0 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 Contrary to the
2a200 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e intuition of man
2a210 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 y, [sqlite3_rese
2a220 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 t()] does not re
2a230 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 set.** the [sqli
2a240 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 te3_bind_blob |
2a250 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b bindings] on a [
2a260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a270 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 nt]..** ^Use thi
2a280 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 s routine to res
2a290 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 et all host para
2a2a0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a meters to NULL..
2a2b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2a2c0 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f t sqlite3_clear_
2a2d0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 bindings(sqlite3
2a2e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 _stmt*);../*.**
2a2f0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 CAPI3REF: Number
2a300 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 Of Columns In A
2a310 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a Result Set.**.*
2a320 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 * ^Return the nu
2a330 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
2a340 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 in the result se
2a350 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 t returned by th
2a360 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2a370 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 tatement]. ^This
2a380 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2a390 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 0 if pStmt is a
2a3a0 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 n SQL.** stateme
2a3b0 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 nt that does not
2a3c0 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f return data (fo
2a3d0 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 r example an [UP
2a3e0 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 DATE])..**.** Se
2a3f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2a400 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a _data_count()].*
2a410 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2a420 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2a430 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
2a440 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2a450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c ** CAPI3REF: Col
2a460 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 umn Names In A R
2a470 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 esult Set.**.**
2a480 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
2a490 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
2a4a0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
2a4b0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
2a4c0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
2a4d0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
2a4e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e T] statement. ^
2a4f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
2a500 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 mn_name().** int
2a510 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2a520 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
2a530 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
2a540 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e F-8 string.** an
2a550 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2a560 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e _name16() return
2a570 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
2a580 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2a590 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
2a5a0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 g. ^The first p
2a5b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2a5c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2a5d0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 ent].** that imp
2a5e0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c lements the [SEL
2a5f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
2a600 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
2a610 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
2a620 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 column number.
2a630 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f ^The leftmost co
2a640 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 lumn is number 0
2a650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ..**.** ^The ret
2a660 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
2a670 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
2a680 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
2a690 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2a6a0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
2a6b0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
2a6c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
2a6d0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 ntil the stateme
2a6e0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 nt is automatica
2a6f0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 lly.** reprepare
2a700 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 d by the first c
2a710 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2a720 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 step()] for a pa
2a730 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 rticular run.**
2a740 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 or until the nex
2a750 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c t call to.** sql
2a760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2a770 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f () or sqlite3_co
2a780 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e lumn_name16() on
2a790 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e the same column
2a7a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ..**.** ^If sqli
2a7b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
2a7c0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
2a7d0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
2a7e0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
2a7f0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
2a800 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
2a810 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
2a820 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
2a830 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
2a840 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
2a850 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
2a860 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
2a870 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
2a880 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
2a890 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
2a8a0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
2a8b0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
2a8c0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
2a8d0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
2a8e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
2a8f0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
2a900 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
2a910 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
2a920 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
2a930 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 o the next..*/.S
2a940 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2a950 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2a960 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 lumn_name(sqlite
2a970 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
2a980 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2a990 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
2a9a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 column_name16(sq
2a9b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2a9c0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 N);../*.** CAPI
2a9d0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 3REF: Source Of
2a9e0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 Data In A Query
2a9f0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 Result.**.** ^Th
2aa00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f ese routines pro
2aa10 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 vide a means to
2aa20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 determine the da
2aa30 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 tabase, table, a
2aa40 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 nd.** table colu
2aa50 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f mn that is the o
2aa60 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 rigin of a parti
2aa70 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c cular result col
2aa80 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 umn in.** [SELEC
2aa90 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a T] statement..**
2aaa0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 ^The name of th
2aab0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 e database or ta
2aac0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 ble or column ca
2aad0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 n be returned as
2aae0 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 .** either a UTF
2aaf0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 -8 or UTF-16 str
2ab00 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 ing. ^The _data
2ab10 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 base_ routines r
2ab20 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 eturn.** the dat
2ab30 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 abase name, the
2ab40 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 _table_ routines
2ab50 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c return the tabl
2ab60 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 e name, and.** t
2ab70 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 he origin_ routi
2ab80 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 nes return the c
2ab90 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e olumn name..** ^
2aba0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2abb0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ing is valid unt
2abc0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 il the [prepared
2abd0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 statement] is d
2abe0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e estroyed.** usin
2abf0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c g [sqlite3_final
2ac00 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 ize()] or until
2ac10 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
2ac20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
2ac30 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 * reprepared by
2ac40 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 the first call t
2ac50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
2ac60 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 )] for a particu
2ac70 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e lar run.** or un
2ac80 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 til the same inf
2ac90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 ormation is requ
2aca0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 ested.** again i
2acb0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e n a different en
2acc0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 coding..**.** ^T
2acd0 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 he names returne
2ace0 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e d are the origin
2acf0 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 al un-aliased na
2ad00 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 mes of the.** da
2ad10 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 tabase, table, a
2ad20 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a nd column..**.**
2ad30 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
2ad40 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e ment to these in
2ad50 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 terfaces is a [p
2ad60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2ad70 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 t]..** ^These fu
2ad80 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 nctions return i
2ad90 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
2ada0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 the Nth result
2adb0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
2adc0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d by.** the statem
2add0 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 ent, where N is
2ade0 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 the second funct
2adf0 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ion argument..**
2ae00 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 ^The left-most
2ae10 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e column is column
2ae20 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 0 for these rou
2ae30 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 tines..**.** ^If
2ae40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
2ae50 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 returned by the
2ae60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 statement is an
2ae70 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a expression or.**
2ae80 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 subquery and is
2ae90 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 not a column va
2aea0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 lue, then all of
2aeb0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
2aec0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e return.** NULL.
2aed0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ^These routine
2aee0 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 might also retu
2aef0 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d rn NULL if a mem
2af00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
2af10 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 rror.** occurs.
2af20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 ^Otherwise, the
2af30 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d y return the nam
2af40 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 e of the attache
2af50 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c d database, tabl
2af60 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 e,.** or column
2af70 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c that query resul
2af80 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 t column was ext
2af90 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a racted from..**.
2afa0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 ** ^As with all
2afb0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 other SQLite API
2afc0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e s, those whose n
2afd0 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 ames end with "1
2afe0 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 6" return.** UTF
2aff0 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 -16 encoded stri
2b000 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 ngs and the othe
2b010 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 r functions retu
2b020 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 rn UTF-8..**.**
2b030 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 ^These APIs are
2b040 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
2b050 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 f the library wa
2b060 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
2b070 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 the.** [SQLITE_E
2b080 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 NABLE_COLUMN_MET
2b090 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 ADATA] C-preproc
2b0a0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a essor symbol..**
2b0b0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f .** If two or mo
2b0c0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 re threads call
2b0d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 one or more of t
2b0e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 hese routines ag
2b0f0 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a ainst the same.*
2b100 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 * prepared state
2b110 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 ment and column
2b120 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
2b130 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2b140 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e s are.** undefin
2b150 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f ed..**.** If two
2b160 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
2b170 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
2b180 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
2b190 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
2b1a0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 me | column meta
2b1b0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d data interfaces]
2b1c0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 .** for the same
2b1d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2b1e0 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 ment] and result
2b1f0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 column.** at th
2b200 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e e same time then
2b210 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
2b220 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 undefined..*/.S
2b230 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2b240 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2b250 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 lumn_database_na
2b260 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2b270 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
2b280 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2b290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 lite3_column_dat
2b2a0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c abase_name16(sql
2b2b0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
2b2c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2b2d0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2b2e0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d column_table_nam
2b2f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2b300 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2b310 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
2b320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c ite3_column_tabl
2b330 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
2b340 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2b350 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2b360 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2b370 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 mn_origin_name(s
2b380 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2b390 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
2b3a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2b3b0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
2b3c0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2b3d0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
2b3e0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
2b3f0 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
2b400 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2b410 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 **.** ^(The firs
2b420 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 t parameter is a
2b430 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2b440 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 ment]..** If thi
2b450 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 s statement is a
2b460 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2b470 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 ent and the Nth
2b480 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a column of the.**
2b490 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 returned result
2b4a0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 set of that [SE
2b4b0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 LECT] is a table
2b4c0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a column (not an.
2b4d0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
2b4e0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 subquery) then
2b4f0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
2b500 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a e of the table.*
2b510 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 * column is retu
2b520 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 rned.)^ ^If the
2b530 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
2b540 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 he result set is
2b550 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
2b560 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 n or subquery, t
2b570 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 hen a NULL point
2b580 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
2b590 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
2b5a0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 string is alway
2b5b0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e s UTF-8 encoded.
2b5c0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 .**.** ^(For exa
2b5d0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 mple, given the
2b5e0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
2b5f0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
2b600 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
2b610 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 T);.**.** and th
2b620 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
2b630 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
2b640 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 iled:.**.** SELE
2b650 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 CT c1 + 1, c1 FR
2b660 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 OM t1;.**.** thi
2b670 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 s routine would
2b680 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e return the strin
2b690 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 g "VARIANT" for
2b6a0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c the second resul
2b6b0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d t.** column (i==
2b6c0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 1), and a NULL p
2b6d0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 ointer for the f
2b6e0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 irst result colu
2b6f0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a mn (i==0).)^.**.
2b700 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
2b710 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 dynamic run-time
2b720 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 typing. ^So ju
2b730 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c st because a col
2b740 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 umn.** is declar
2b750 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 ed to contain a
2b760 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 particular type
2b770 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 does not mean th
2b780 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 at the.** data s
2b790 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f tored in that co
2b7a0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 lumn is of the d
2b7b0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 eclared type. S
2b7c0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f QLite is.** stro
2b7d0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 ngly typed, but
2b7e0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 the typing is dy
2b7f0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 namic not static
2b800 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 . ^Type.** is a
2b810 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 ssociated with i
2b820 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 ndividual values
2b830 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 , not with the c
2b840 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 ontainers.** use
2b850 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 d to hold those
2b860 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 values..*/.SQLIT
2b870 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2b880 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2b890 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 _decltype(sqlite
2b8a0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 3_stmt*,int);.SQ
2b8b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
2b8c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c oid *sqlite3_col
2b8d0 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 umn_decltype16(s
2b8e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2b8f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2b900 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 EF: Evaluate An
2b910 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a SQL Statement.**
2b920 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 .** After a [pre
2b930 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b940 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 has been prepar
2b950 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a ed using either.
2b960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
2b970 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
2b980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2b990 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 v2()] or one of
2b9a0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e the legacy.** in
2b9b0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 terfaces [sqlite
2b9c0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
2b9d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2b9e0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 16()], this func
2b9f0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 tion.** must be
2ba00 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f called one or mo
2ba10 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c re times to eval
2ba20 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 uate the stateme
2ba30 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 nt..**.** The de
2ba40 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 tails of the beh
2ba50 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c avior of the sql
2ba60 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 ite3_step() inte
2ba70 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 rface depend.**
2ba80 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 on whether the s
2ba90 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 tatement was pre
2baa0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 pared using the
2bab0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 newer "v2" inter
2bac0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 face.** [sqlite3
2bad0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
2bae0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
2baf0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 are16_v2()] or t
2bb00 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a he older legacy.
2bb10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 ** interface [sq
2bb20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
2bb30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
2bb40 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 epare16()]. The
2bb50 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e use of the.** n
2bb60 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 ew "v2" interfac
2bb70 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e is recommended
2bb80 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 for new applica
2bb90 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 tions but the le
2bba0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
2bbb0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 e will continue
2bbc0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e to be supported.
2bbd0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c .**.** ^In the l
2bbe0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c egacy interface,
2bbf0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
2bc00 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 e will be either
2bc10 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a [SQLITE_BUSY],.
2bc20 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d ** [SQLITE_DONE]
2bc30 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 , [SQLITE_ROW],
2bc40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 [SQLITE_ERROR],
2bc50 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 or [SQLITE_MISUS
2bc60 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 E]..** ^With the
2bc70 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
2bc80 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 any of the othe
2bc90 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d r [result codes]
2bca0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
2bcb0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d result codes] m
2bcc0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 ight be returned
2bcd0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 as well..**.**
2bce0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d ^[SQLITE_BUSY] m
2bcf0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 eans that the da
2bd00 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 tabase engine wa
2bd10 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 s unable to acqu
2bd20 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ire the.** datab
2bd30 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 ase locks it nee
2bd40 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 ds to do its job
2bd50 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 . ^If the state
2bd60 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 ment is a [COMMI
2bd70 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 T].** or occurs
2bd80 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 outside of an ex
2bd90 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
2bda0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e on, then you can
2bdb0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 retry the.** st
2bdc0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 atement. If the
2bdd0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f statement is no
2bde0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 t a [COMMIT] and
2bdf0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
2be00 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 n.** explicit tr
2be10 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 ansaction then y
2be20 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 ou should rollba
2be30 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ck the transacti
2be40 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e on before.** con
2be50 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e tinuing..**.** ^
2be60 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 [SQLITE_DONE] me
2be70 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 ans that the sta
2be80 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 tement has finis
2be90 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a hed executing.**
2bea0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 successfully.
2beb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 sqlite3_step() s
2bec0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c hould not be cal
2bed0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 led again on thi
2bee0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 s virtual.** mac
2bef0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 hine without fir
2bf00 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 st calling [sqli
2bf10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 te3_reset()] to
2bf20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 reset the virtua
2bf30 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 l.** machine bac
2bf40 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c k to its initial
2bf50 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 state..**.** ^I
2bf60 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
2bf70 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 ent being execut
2bf80 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 ed returns any d
2bf90 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ata, then [SQLIT
2bfa0 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 E_ROW].** is ret
2bfb0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 urned each time
2bfc0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 a new row of dat
2bfd0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 a is ready for p
2bfe0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 rocessing by the
2bff0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 .** caller. The
2c000 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 values may be ac
2c010 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 cessed using the
2c020 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 [column access
2c030 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 functions]..** s
2c040 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 qlite3_step() is
2c050 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f called again to
2c060 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 retrieve the ne
2c070 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a xt row of data..
2c080 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 **.** ^[SQLITE_E
2c090 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 RROR] means that
2c0a0 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f a run-time erro
2c0b0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e r (such as a con
2c0c0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 straint.** viola
2c0d0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 tion) has occurr
2c0e0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 ed. sqlite3_ste
2c0f0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 p() should not b
2c100 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f e called again o
2c110 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 n.** the VM. Mor
2c120 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 e information ma
2c130 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 y be found by ca
2c140 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 lling [sqlite3_e
2c150 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 rrmsg()]..** ^Wi
2c160 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e th the legacy in
2c170 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 terface, a more
2c180 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
2c190 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 ode (for example
2c1a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 ,.** [SQLITE_INT
2c1b0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 ERRUPT], [SQLITE
2c1c0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 _SCHEMA], [SQLIT
2c1d0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 E_CORRUPT], and
2c1e0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e so forth).** can
2c1f0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 be obtained by
2c200 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
2c210 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 _reset()] on the
2c220 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
2c230 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 atement]. ^In t
2c240 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
2c250 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 e,.** the more s
2c260 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
2c270 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 de is returned d
2c280 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 irectly by sqlit
2c290 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a e3_step()..**.**
2c2a0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2c2b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
2c2c0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 this routine was
2c2d0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 called inapprop
2c2e0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 riately..** Perh
2c2f0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 aps it was calle
2c300 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 d on a [prepared
2c310 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
2c320 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 has.** already
2c330 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 been [sqlite3_fi
2c340 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
2c350 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 ed] or on one th
2c360 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f at had.** previo
2c370 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 usly returned [S
2c380 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 QLITE_ERROR] or
2c390 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2c3a0 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 Or it could.** b
2c3b0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
2c3c0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
2c3d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
2c3e0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 being used by tw
2c3f0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 o or.** more thr
2c400 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
2c410 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e moment in time.
2c420 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 .**.** For all v
2c430 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
2c440 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c e up to and incl
2c450 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 uding 3.6.23.1,
2c460 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 a call to.** [sq
2c470 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 lite3_reset()] w
2c480 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 as required afte
2c490 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 r sqlite3_step()
2c4a0 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 returned anythi
2c4b0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e ng.** other than
2c4c0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 [SQLITE_ROW] be
2c4d0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 fore any subsequ
2c4e0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ent invocation o
2c4f0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 f.** sqlite3_ste
2c500 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f p(). Failure to
2c510 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 reset the prepa
2c520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 red statement us
2c530 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
2c540 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 _reset()] would
2c550 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 result in an [SQ
2c560 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 LITE_MISUSE] ret
2c570 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 urn from.** sqli
2c580 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 te3_step(). But
2c590 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 after version 3
2c5a0 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 .6.23.1, sqlite3
2c5b0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a _step() began.**
2c5c0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2c5d0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 3_reset()] autom
2c5e0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 atically in this
2c5f0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 circumstance ra
2c600 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 ther.** than ret
2c610 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d urning [SQLITE_M
2c620 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 ISUSE]. This is
2c630 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 not considered
2c640 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a a compatibility.
2c650 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 ** break because
2c660 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e any application
2c670 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 that ever recei
2c680 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 ves an SQLITE_MI
2c690 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 SUSE error.** is
2c6a0 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e broken by defin
2c6b0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c ition. The [SQL
2c6c0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 ITE_OMIT_AUTORES
2c6d0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ET] compile-time
2c6e0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 option.** can b
2c6f0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 e used to restor
2c700 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 e the legacy beh
2c710 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e avior..**.** <b>
2c720 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 Goofy Interface
2c730 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 Alert:</b> In th
2c740 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 e legacy interfa
2c750 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f ce, the sqlite3_
2c760 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c step().** API al
2c770 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 ways returns a g
2c780 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 eneric error cod
2c790 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 e, [SQLITE_ERROR
2c7a0 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ], following any
2c7b0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 .** error other
2c7c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 than [SQLITE_BUS
2c7d0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d Y] and [SQLITE_M
2c7e0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 ISUSE]. You mus
2c7f0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 t call.** [sqlit
2c800 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
2c810 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2c820 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ()] in order to
2c830 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a find one of the.
2c840 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 ** specific [err
2c850 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 or codes] that b
2c860 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 etter describes
2c870 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 the error..** We
2c880 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 admit that this
2c890 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 is a goofy desi
2c8a0 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d gn. The problem
2c8b0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a has been fixed.
2c8c0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 ** with the "v2"
2c8d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 interface. If
2c8e0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 you prepare all
2c8f0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 of your SQL stat
2c900 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 ements.** using
2c910 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f either [sqlite3_
2c920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2c930 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2c940 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 e16_v2()] instea
2c950 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 d.** of the lega
2c960 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 cy [sqlite3_prep
2c970 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 are()] and [sqli
2c980 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
2c990 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 interfaces,.**
2c9a0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 then the more sp
2c9b0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f ecific [error co
2c9c0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 des] are returne
2c9d0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 d directly.** by
2c9e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e sqlite3_step().
2c9f0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 The use of the
2ca00 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
2ca10 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a is recommended..
2ca20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2ca30 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 t sqlite3_step(s
2ca40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
2ca50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ca60 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e Number of column
2ca70 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 s in a result se
2ca80 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2ca90 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 ite3_data_count(
2caa0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
2cab0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2cac0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2cad0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 e.** current row
2cae0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2caf0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 et of [prepared
2cb00 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a statement] P..**
2cb10 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 ^If prepared st
2cb20 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e atement P does n
2cb30 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 ot have results
2cb40 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a ready to return.
2cb50 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f ** (via calls to
2cb60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f the [sqlite3_co
2cb70 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 lumn_int | sqlit
2cb80 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f e3_column_*()] o
2cb90 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 f.** interfaces)
2cba0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 then sqlite3_da
2cbb0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 ta_count(P) retu
2cbc0 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 rns 0..** ^The s
2cbd0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2cbe0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 t(P) routine als
2cbf0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 o returns 0 if P
2cc00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
2cc10 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 er..** ^The sqli
2cc20 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2cc30 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
2cc40 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 s 0 if the previ
2cc50 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b ous call to.** [
2cc60 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 sqlite3_step](P)
2cc70 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 returned [SQLIT
2cc80 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 E_DONE]. ^The s
2cc90 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e qlite3_data_coun
2cca0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 t(P).** will ret
2ccb0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 urn non-zero if
2ccc0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
2ccd0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 [sqlite3_step](
2cce0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b P) returned.** [
2ccf0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 SQLITE_ROW], exc
2cd00 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 ept in the case
2cd10 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 of the [PRAGMA i
2cd20 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 ncremental_vacuu
2cd30 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 m].** where it a
2cd40 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 lways returns ze
2cd50 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 ro since each st
2cd60 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 ep of that multi
2cd70 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 -step.** pragma
2cd80 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e returns 0 column
2cd90 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a s of data..**.**
2cda0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2cdb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
2cdc0 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ()].*/.SQLITE_AP
2cdd0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 I int sqlite3_da
2cde0 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 ta_count(sqlite3
2cdf0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
2ce00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2ce10 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 Fundamental Data
2ce20 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 types.** KEYWORD
2ce30 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a S: SQLITE_TEXT.*
2ce40 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c *.** ^(Every val
2ce50 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 ue in SQLite has
2ce60 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e one of five fun
2ce70 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 damental datatyp
2ce80 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a es:.**.** <ul>.*
2ce90 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 * <li> 64-bit si
2cea0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
2ceb0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 <li> 64-bit IEEE
2cec0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
2ced0 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 number.** <li> s
2cee0 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c tring.** <li> BL
2cef0 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a OB.** <li> NULL.
2cf00 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
2cf10 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
2cf20 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 are codes for e
2cf30 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 ach of those typ
2cf40 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 es..**.** Note t
2cf50 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hat the SQLITE_T
2cf60 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 EXT constant was
2cf70 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 also used in SQ
2cf80 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a Lite version 2.*
2cf90 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 * for a complete
2cfa0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 ly different mea
2cfb0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 ning. Software
2cfc0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e that links again
2cfd0 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 st both.** SQLit
2cfe0 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 e version 2 and
2cff0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
2d000 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 should use SQLI
2d010 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a TE3_TEXT, not.**
2d020 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f SQLITE_TEXT..*/
2d030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2d040 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 INTEGER 1.#defi
2d050 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 ne SQLITE_FLOAT
2d060 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
2d070 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 ITE_BLOB 4.#
2d080 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 define SQLITE_NU
2d090 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 LL 5.#ifdef
2d0a0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e SQLITE_TEXT.# un
2d0b0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
2d0c0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 #else.# define S
2d0d0 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 QLITE_TEXT 3
2d0e0 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 .#endif.#define
2d0f0 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 SQLITE3_TEXT
2d100 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3../*.** CAPI3R
2d110 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 EF: Result Value
2d120 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a s From A Query.*
2d130 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c * KEYWORDS: {col
2d140 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 umn access funct
2d150 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ions}.**.** Thes
2d160 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 e routines form
2d170 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 the "result set"
2d180 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
2d190 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
2d1a0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 s return informa
2d1b0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e tion about a sin
2d1c0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 gle column of th
2d1d0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 e current.** res
2d1e0 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 ult row of a que
2d1f0 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 ry. ^In every c
2d200 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 ase the first ar
2d210 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
2d220 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 ter.** to the [p
2d230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d240 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 t] that is being
2d250 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 evaluated (the
2d260 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a [sqlite3_stmt*].
2d270 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 ** that was retu
2d280 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 rned from [sqlit
2d290 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2d2a0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 or one of its v
2d2b0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 ariants).** and
2d2c0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
2d2d0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 ent is the index
2d2e0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 of the column f
2d2f0 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 or which informa
2d300 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
2d310 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 e returned. ^The
2d320 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e leftmost column
2d330 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 of the result s
2d340 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 et has the index
2d350 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 0..** ^The numb
2d360 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
2d370 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 the result can
2d380 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 be determined us
2d390 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
2d3a0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e column_count()].
2d3b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 .**.** If the SQ
2d3c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 L statement does
2d3d0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 not currently p
2d3e0 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 oint to a valid
2d3f0 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a row, or if the.*
2d400 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 * column index i
2d410 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 s out of range,
2d420 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e the result is un
2d430 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 defined..** Thes
2d440 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f e routines may o
2d450 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 nly be called wh
2d460 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 en the most rece
2d470 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 nt call to.** [s
2d480 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 qlite3_step()] h
2d490 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c as returned [SQL
2d4a0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 ITE_ROW] and nei
2d4b0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ther.** [sqlite3
2d4c0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 _reset()] nor [s
2d4d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2d4e0 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c )] have been cal
2d4f0 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 led subsequently
2d500 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 ..** If any of t
2d510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
2d520 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b e called after [
2d530 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2d540 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
2d550 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 finalize()] or a
2d560 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 fter [sqlite3_st
2d570 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e ep()] has return
2d580 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 ed.** something
2d590 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
2d5a0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 TE_ROW], the res
2d5b0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e ults are undefin
2d5c0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 ed..** If [sqlit
2d5d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 e3_step()] or [s
2d5e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2d5f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 or [sqlite3_fina
2d600 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 lize()].** are c
2d610 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 alled from a dif
2d620 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 ferent thread wh
2d630 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 ile any of these
2d640 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 routines.** are
2d650 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 pending, then t
2d660 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
2d670 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2d680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^The sqlite3_col
2d690 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 umn_type() routi
2d6a0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a ne returns the.*
2d6b0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 * [SQLITE_INTEGE
2d6c0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 R | datatype cod
2d6d0 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 e] for the initi
2d6e0 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 al data type.**
2d6f0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f of the result co
2d700 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 lumn. ^The retu
2d710 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e rned value is on
2d720 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 e of [SQLITE_INT
2d730 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 EGER],.** [SQLIT
2d740 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 E_FLOAT], [SQLIT
2d750 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 E_TEXT], [SQLITE
2d760 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 _BLOB], or [SQLI
2d770 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 TE_NULL]. The v
2d780 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
2d790 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
2d7a0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c mn_type() is onl
2d7b0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 y meaningful if
2d7c0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 no type.** conve
2d7d0 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 rsions have occu
2d7e0 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 rred as describe
2d7f0 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 d below. After
2d800 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
2d810 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 n,.** the value
2d820 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
2d830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
2d840 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 ) is undefined.
2d850 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 Future.** versi
2d860 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 ons of SQLite ma
2d870 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 y change the beh
2d880 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 avior of sqlite3
2d890 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a _column_type().*
2d8a0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 * following a ty
2d8b0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a pe conversion..*
2d8c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 *.** ^If the res
2d8d0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
2d8e0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 UTF-8 string th
2d8f0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2d900 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a olumn_bytes().**
2d910 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2d920 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2d930 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f ytes in that BLO
2d940 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 B or string..**
2d950 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2d960 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e s a UTF-16 strin
2d970 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f g, then sqlite3_
2d980 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 column_bytes() c
2d990 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
2d9a0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 tring to UTF-8 a
2d9b0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 nd then returns
2d9c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2d9d0 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 tes..** ^If the
2d9e0 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 result is a nume
2d9f0 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 ric value then s
2da00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2da10 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 tes() uses.** [s
2da20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
2da30 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 )] to convert th
2da40 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 at value to a UT
2da50 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 F-8 string and r
2da60 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
2da70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
2da80 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
2da90 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
2daa0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 is NULL, then sq
2dab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2dac0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 es() returns zer
2dad0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 o..**.** ^If the
2dae0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
2daf0 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 B or UTF-16 stri
2db00 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 ng then the sqli
2db10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2db20 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 16().** routine
2db30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2db40 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
2db50 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 hat BLOB or stri
2db60 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
2db70 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 esult is a UTF-8
2db80 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
2db90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2dba0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a es16() converts.
2dbb0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f ** the string to
2dbc0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e UTF-16 and then
2dbd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
2dbe0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a ber of bytes..**
2dbf0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
2dc00 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c is a numeric val
2dc10 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ue then sqlite3_
2dc20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2dc30 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2dc40 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2dc50 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2dc60 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 lue to a UTF-16
2dc70 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
2dc80 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ns.** the number
2dc90 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
2dca0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 t string..** ^If
2dcb0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e the result is N
2dcc0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ULL, then sqlite
2dcd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2dce0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e () returns zero.
2dcf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 .**.** ^The valu
2dd00 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b es returned by [
2dd10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2dd20 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 ytes()] and .**
2dd30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2dd40 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f bytes16()] do no
2dd50 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 t include the ze
2dd60 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 ro terminators a
2dd70 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 t the end.** of
2dd80 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f the string. ^Fo
2dd90 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 r clarity: the v
2dda0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
2ddb0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
2ddc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e lumn_bytes()] an
2ddd0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d [sqlite3_colum
2dde0 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 n_bytes16()] are
2ddf0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
2de00 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 * bytes in the s
2de10 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e tring, not the n
2de20 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 umber of charact
2de30 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 ers..**.** ^Stri
2de40 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
2de50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2de60 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ext() and sqlite
2de70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
2de80 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 ),.** even empty
2de90 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c strings, are al
2dea0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e ways zero-termin
2deb0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 ated. ^The retu
2dec0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d rn.** value from
2ded0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2dee0 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 blob() for a zer
2def0 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 o-length BLOB is
2df00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
2df10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 .**.** ^The obje
2df20 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ct returned by [
2df30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2df40 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a alue()] is an.**
2df50 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2df60 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2df70 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 ect. An unprote
2df80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2df90 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 ue object.** may
2dfa0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 only be used wi
2dfb0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 th [sqlite3_bind
2dfc0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
2dfd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
2dfe0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 lue()]..** If th
2dff0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 e [unprotected s
2e000 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
2e010 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
2e020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2e030 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
2e040 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 used in any othe
2e050 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 r way, including
2e060 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 calls.** to rou
2e070 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 tines like [sqli
2e080 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d te3_value_int()]
2e090 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
2e0a0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
2e0b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
2e0c0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 ytes()], then th
2e0d0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
2e0e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 defined..**.** T
2e0f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 hese routines at
2e100 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 tempt to convert
2e110 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 the value where
2e120 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e appropriate. ^
2e130 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
2e140 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 if the internal
2e150 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 representation i
2e160 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 s FLOAT and a te
2e170 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 xt result.** is
2e180 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 requested, [sqli
2e190 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
2e1a0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
2e1b0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ly to perform th
2e1c0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e.** conversion
2e1d0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
2e1e0 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 ^(The following
2e1f0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 table details th
2e200 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a e conversions.**
2e210 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 that are applie
2e220 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 d:.**.** <blockq
2e230 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 uote>.** <table
2e240 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c border="1">.** <
2e250 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c tr><th> Internal
2e260 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 <br>Type <th> Re
2e270 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 quested<br>Type
2e280 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e <th> Conversion
2e290 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
2e2a0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e NULL <td> IN
2e2b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 TEGER <td> Res
2e2c0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e ult is 0.** <tr>
2e2d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
2e2e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
2e2f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a > Result is 0.0.
2e300 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
2e310 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 L <td> TEXT
2e320 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
2e330 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
2e340 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e r.** <tr><td> N
2e350 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c ULL <td> BL
2e360 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c OB <td> Resul
2e370 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
2e380 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ter.** <tr><td>
2e390 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 INTEGER <td> F
2e3a0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e LOAT <td> Con
2e3b0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 vert from intege
2e3c0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 r to float.** <t
2e3d0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
2e3e0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2e3f0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
2e400 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 ing of the integ
2e410 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
2e420 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 NTEGER <td> B
2e430 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 LOB <td> Same
2e440 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 as INTEGER->TEX
2e450 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 T.** <tr><td> F
2e460 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOAT <td> INTE
2e470 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
2e480 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
2e490 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2e4a0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
2e4b0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
2e4c0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f ering of the flo
2e4d0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 at.** <tr><td>
2e4e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 FLOAT <td> B
2e4f0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 LOB <td> [CAS
2e500 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 T] to BLOB.** <t
2e510 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2e520 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
2e530 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e td> [CAST] to IN
2e540 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 TEGER.** <tr><td
2e550 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
2e560 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b FLOAT <td> [
2e570 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a CAST] to REAL.**
2e580 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
2e590 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2e5a0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 <td> No change
2e5b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
2e5c0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OB <td> INTEG
2e5d0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d ER <td> [CAST]
2e5e0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c to INTEGER.** <
2e5f0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2e600 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
2e610 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 <td> [CAST] to R
2e620 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EAL.** <tr><td>
2e630 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
2e640 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
2e650 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
2e660 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
2e670 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
2e680 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
2e690 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 * The table abov
2e6a0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 e makes referenc
2e6b0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 e to standard C
2e6c0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e library function
2e6d0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 s atoi().** and
2e6e0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 atof(). SQLite
2e6f0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 does not really
2e700 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 use these functi
2e710 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 ons. It has its
2e720 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 .** own equivale
2e730 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 nt internal rout
2e740 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 ines. The atoi(
2e750 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d ) and atof() nam
2e760 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 es are.** used i
2e770 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 n the table for
2e780 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 brevity and beca
2e790 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d use they are fam
2e7a0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a iliar to most.**
2e7b0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a C programmers..
2e7c0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2e7d0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 when type conver
2e7e0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 sions occur, poi
2e7f0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 nters returned b
2e800 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 y prior.** calls
2e810 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2e820 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 mn_blob(), sqlit
2e830 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2e840 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 , and/or.** sqli
2e850 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2e860 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 6() may be inval
2e870 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 idated..** Type
2e880 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 conversions and
2e890 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 pointer invalida
2e8a0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 tions might occu
2e8b0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c r.** in the foll
2e8c0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a owing cases:.**.
2e8d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
2e8e0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2e8f0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e ent is a BLOB an
2e900 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2e910 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 _text() or.**
2e920 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
2e930 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
2e940 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 lled. A zero-te
2e950 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a rminator might.*
2e960 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 * need to b
2e970 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 e added to the s
2e980 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c tring.</li>.** <
2e990 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2e9a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 content is UTF-8
2e9b0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
2e9c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2e9d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2e9e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2e9f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2ea00 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
2ea10 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
2ea20 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 ** to UTF-1
2ea30 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 6.</li>.** <li>
2ea40 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2ea50 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 ent is UTF-16 te
2ea60 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
2ea70 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
2ea80 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2ea90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 _column_text() i
2eaa0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
2eab0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
2eac0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
2ead0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a to UTF-8.</li>.
2eae0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e ** </ul>.**.** ^
2eaf0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 Conversions betw
2eb00 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 een UTF-16be and
2eb10 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c UTF-16le are al
2eb20 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 ways done in pla
2eb30 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 ce and do.** not
2eb40 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 invalidate a pr
2eb50 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f ior pointer, tho
2eb60 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
2eb70 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2eb80 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
2eb90 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 the prior pointe
2eba0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c r references wil
2ebb0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 l have been modi
2ebc0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e fied. Other kin
2ebd0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 ds.** of convers
2ebe0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 ion are done in
2ebf0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 place when it is
2ec00 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 possible, but s
2ec10 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a ometimes they.**
2ec20 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c are not possibl
2ec30 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 e and in those c
2ec40 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 ases prior point
2ec50 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 ers are invalida
2ec60 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ted..**.** The s
2ec70 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 afest and easies
2ec80 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f t to remember po
2ec90 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b licy is to invok
2eca0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
2ecb0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 .** in one of th
2ecc0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 e following ways
2ecd0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
2ece0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2ecf0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f umn_text() follo
2ed00 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
2ed10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
2ed20 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
2ed30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2ed40 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
2ed50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2ed60 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
2ed70 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2ed80 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 text16() followe
2ed90 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2eda0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c umn_bytes16()</l
2edb0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
2edc0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
2edd0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c , you should cal
2ede0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e l sqlite3_column
2edf0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 _text(),.** sqli
2ee00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2ee10 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f ), or sqlite3_co
2ee20 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 lumn_text16() fi
2ee30 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 rst to force the
2ee40 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 result.** into
2ee50 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d the desired form
2ee60 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 at, then invoke
2ee70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2ee80 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c ytes() or.** sql
2ee90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2eea0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 s16() to find th
2eeb0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 e size of the re
2eec0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 sult. Do not mi
2eed0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 x calls.** to sq
2eee0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2eef0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 t() or sqlite3_c
2ef00 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 olumn_blob() wit
2ef10 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 h calls to.** sq
2ef20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2ef30 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e es16(), and do n
2ef40 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 ot mix calls to
2ef50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ef60 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 ext16().** with
2ef70 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2ef80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e _column_bytes().
2ef90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e .**.** ^The poin
2efa0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 ters returned ar
2efb0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 e valid until a
2efc0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 type conversion
2efd0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 occurs as.** des
2efe0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 cribed above, or
2eff0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f until [sqlite3_
2f000 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
2f010 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
2f020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
2f030 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 lize()] is calle
2f040 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 d. ^The memory
2f050 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f space used to ho
2f060 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e ld strings.** an
2f070 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 d BLOBs is freed
2f080 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
2f090 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 Do <b>not</b> p
2f0a0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 ass the pointers
2f0b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f returned.** fro
2f0c0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d m [sqlite3_colum
2f0d0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 n_blob()], [sqli
2f0e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
2f0f0 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a )], etc. into.**
2f100 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
2f110 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 ]..**.** ^(If a
2f120 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
2f130 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 n error occurs d
2f140 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 uring the evalua
2f150 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f tion of any.** o
2f160 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
2f170 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 , a default valu
2f180 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 e is returned.
2f190 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 The default valu
2f1a0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 e.** is either t
2f1b0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 he integer 0, th
2f1c0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 e floating point
2f1d0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 number 0.0, or
2f1e0 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
2f1f0 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 r. Subsequent c
2f200 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2f210 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c _errcode()] will
2f220 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
2f230 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a TE_NOMEM].)^.*/.
2f240 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2f250 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2f260 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
2f270 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f280 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
2f290 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2f2a0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 mn_bytes(sqlite3
2f2b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2f2c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2f2d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
2f2e0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 _bytes16(sqlite3
2f2f0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
2f300 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f );.SQLITE_API do
2f310 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c uble sqlite3_col
2f320 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 umn_double(sqlit
2f330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2f340 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
2f350 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 int sqlite3_colu
2f360 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 mn_int(sqlite3_s
2f370 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2f380 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
2f390 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 te3_int64 sqlite
2f3a0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 3_column_int64(s
2f3b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2f3c0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
2f3d0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e API const unsign
2f3e0 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 ed char *sqlite3
2f3f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c _column_text(sql
2f400 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2f410 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
2f420 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
2f430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2f440 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t16(sqlite3_stmt
2f450 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
2f460 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2f470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
2f480 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2f490 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
2f4a0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 E_API sqlite3_va
2f4b0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c lue *sqlite3_col
2f4c0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 umn_value(sqlite
2f4d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2f4e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
2f4f0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 REF: Destroy A P
2f500 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
2f510 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e t Object.**.** ^
2f520 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 The sqlite3_fina
2f530 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 lize() function
2f540 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c is called to del
2f550 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ete a [prepared
2f560 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e statement]..** ^
2f570 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2f580 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 nt evaluation of
2f590 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 the statement e
2f5a0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 ncountered no er
2f5b0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 rors.** or if th
2f5c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
2f5d0 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 ever been evalua
2f5e0 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ted, then sqlite
2f5f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 3_finalize() ret
2f600 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f urns.** SQLITE_O
2f610 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 K. ^If the most
2f620 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 recent evaluati
2f630 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 on of statement
2f640 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a S failed, then.*
2f650 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 * sqlite3_finali
2f660 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 ze(S) returns th
2f670 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 e appropriate [e
2f680 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a rror code] or.**
2f690 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 [extended error
2f6a0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 code]..**.** ^T
2f6b0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
2f6c0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 ize(S) routine c
2f6d0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 an be called at
2f6e0 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 any point during
2f6f0 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 .** the life cyc
2f700 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 le of [prepared
2f710 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a statement] S:.**
2f720 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e before statemen
2f730 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c t S is ever eval
2f740 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 uated, after.**
2f750 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c one or more call
2f760 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 s to [sqlite3_re
2f770 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 set()], or after
2f780 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 any call.** to
2f790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2f7a0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
2f7b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
2f7c0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a e statement has.
2f7d0 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 ** completed exe
2f7e0 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 cution..**.** ^I
2f7f0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
2f800 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 finalize() on a
2f810 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
2f820 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 a harmless no-op
2f830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c ..**.** The appl
2f840 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e ication must fin
2f850 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 alize every [pre
2f860 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2f870 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f in order to avo
2f880 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c id.** resource l
2f890 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 eaks. It is a g
2f8a0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f rievous error fo
2f8b0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f r the applicatio
2f8c0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a n to try to use.
2f8d0 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 ** a prepared st
2f8e0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
2f8f0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
2f900 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 zed. Any use of
2f910 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 a prepared.** s
2f920 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 tatement after i
2f930 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c t has been final
2f940 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 ized can result
2f950 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 in undefined and
2f960 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 .** undesirable
2f970 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 behavior such as
2f980 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 segfaults and h
2f990 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a eap corruption..
2f9a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
2f9b0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 t sqlite3_finali
2f9c0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ze(sqlite3_stmt
2f9d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2f9e0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 CAPI3REF: Reset
2f9f0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2fa00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a ment Object.**.*
2fa10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
2fa20 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 set() function i
2fa30 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 s called to rese
2fa40 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 t a [prepared st
2fa50 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
2fa60 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ct back to its i
2fa70 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 nitial state, re
2fa80 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 ady to be re-exe
2fa90 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 cuted..** ^Any S
2faa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
2fab0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
2fac0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
2fad0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
2fae0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
2faf0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
2fb00 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
2fb10 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
2fb20 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
2fb30 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
2fb40 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
2fb50 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
2fb60 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 ^The [sqlite3_r
2fb70 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
2fb80 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
2fb90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2fba0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 t] S.** back to
2fbb0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
2fbc0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a its program..**
2fbd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
2fbe0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
2fbf0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2fc00 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 ] for the.** [pr
2fc10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2fc20 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
2fc30 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
2fc40 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f LITE_DONE],.** o
2fc50 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 r if [sqlite3_st
2fc60 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 ep(S)] has never
2fc70 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c before been cal
2fc80 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 led on S,.** the
2fc90 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
2fca0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 (S)] returns [SQ
2fcb0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
2fcc0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
2fcd0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
2fce0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
2fcf0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
2fd00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
2fd10 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 indicated an err
2fd20 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c or, then.** [sql
2fd30 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
2fd40 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
2fd50 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
2fd60 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b e]..**.** ^The [
2fd70 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
2fd80 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 ] interface does
2fd90 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
2fda0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 values.** of any
2fdb0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
2fdc0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e lob|bindings] on
2fdd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
2fde0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a tatement] S..*/.
2fdf0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2fe00 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
2fe10 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2fe20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2fe30 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
2fe40 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
2fe50 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
2fe60 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
2fe70 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
2fe80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
2fe90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2fea0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
2feb0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
2fec0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2fed0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
2fee0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e **.** ^These fun
2fef0 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 ctions (collecti
2ff00 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 vely known as "f
2ff10 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
2ff20 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 routines").** a
2ff30 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
2ff40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
2ff50 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f aggregates or to
2ff60 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 redefine the be
2ff70 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 havior.** of exi
2ff80 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
2ff90 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
2ffa0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 s. The only dif
2ffb0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e ferences between
2ffc0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e .** these routin
2ffd0 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 es are the text
2ffe0 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 encoding expecte
2fff0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 d for.** the sec
30000 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 ond parameter (t
30010 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 he name of the f
30020 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 unction being cr
30030 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 eated).** and th
30040 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 e presence or ab
30050 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 sence of a destr
30060 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 uctor callback f
30070 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 or.** the applic
30080 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
30090 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 er..**.** ^The f
300a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
300b0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
300c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 connection] to w
300d0 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 hich the SQL.**
300e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 function is to b
300f0 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e e added. ^If an
30100 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 application use
30110 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
30120 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
30130 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c ection then appl
30140 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
30150 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
30160 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 st be added.** t
30170 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
30180 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 connection separ
30190 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ately..**.** ^Th
301a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
301b0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
301c0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
301d0 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 on to be created
301e0 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 or.** redefined
301f0 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f . ^The length o
30200 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 f the name is li
30210 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 mited to 255 byt
30220 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a es in a UTF-8.**
30230 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c representation,
30240 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
30250 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f e zero-terminato
30260 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 r. ^Note that t
30270 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 he name.** lengt
30280 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 h limit is in UT
30290 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 F-8 bytes, not c
302a0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 haracters nor UT
302b0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a F-16 bytes. .**
302c0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f ^Any attempt to
302d0 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 create a functi
302e0 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 on with a longer
302f0 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 name.** will re
30300 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f sult in [SQLITE_
30310 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 MISUSE] being re
30320 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
30330 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
30340 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 er (nArg).** is
30350 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
30360 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 guments that the
30370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
30380 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 .** aggregate ta
30390 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 kes. ^If this pa
303a0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 rameter is -1, t
303b0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hen the SQL func
303c0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
303d0 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e gate may take an
303e0 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
303f0 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 ments between 0
30400 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a and the limit.**
30410 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 set by [sqlite3
30420 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
30430 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
30440 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 RG]). If the th
30450 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
30460 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 is less than -1
30470 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
30480 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 127 then the be
30490 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
304a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
304b0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
304c0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 ter, eTextRep, s
304d0 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a pecifies what.**
304e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 [SQLITE_UTF8 |
304f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 text encoding] t
30500 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e his SQL function
30510 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 prefers for.**
30520 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 its parameters.
30530 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
30540 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 should set this
30550 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
30560 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
30570 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f ] if the functio
30580 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
30590 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 invokes .** [sq
305a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
305b0 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16le()] on an in
305c0 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f put, or [SQLITE_
305d0 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a UTF16BE] if the.
305e0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
305f0 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 n invokes [sqlit
30600 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 e3_value_text16b
30610 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 e()] on an input
30620 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f , or.** [SQLITE_
30630 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 UTF16] if [sqlit
30640 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
30650 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b )] is used, or [
30660 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 SQLITE_UTF8].**
30670 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 otherwise. ^The
30680 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 same SQL functi
30690 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
306a0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 ered multiple ti
306b0 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 mes using.** dif
306c0 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 ferent preferred
306d0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c text encodings,
306e0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 with different
306f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
30700 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f for.** each enco
30710 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d ding..** ^When m
30720 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
30730 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
30740 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 ame function are
30750 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 available, SQLi
30760 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 te.** will pick
30770 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 the one that inv
30780 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 olves the least
30790 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 amount of data c
307a0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
307b0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
307c0 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f ameter may optio
307d0 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 nally be ORed wi
307e0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 th [SQLITE_DETER
307f0 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 MINISTIC].** to
30800 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 signal that the
30810 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c function will al
30820 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 ways return the
30830 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 same result give
30840 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e n.** the same in
30850 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 puts within a si
30860 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 ngle SQL stateme
30870 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 nt. Most SQL fu
30880 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 nctions are.** d
30890 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 eterministic. T
308a0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e he built-in [ran
308b0 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 dom()] SQL funct
308c0 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c ion is an exampl
308d0 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 e of a.** functi
308e0 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 on that is not d
308f0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 eterministic. T
30900 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 he SQLite query
30910 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 planner is able
30920 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 to.** perform ad
30930 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a ditional optimiz
30940 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d ations on determ
30950 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e inistic function
30960 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 s, so use.** of
30970 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 the [SQLITE_DETE
30980 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 RMINISTIC] flag
30990 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 is recommended w
309a0 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a here possible..*
309b0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 *.** ^(The fifth
309c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
309d0 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 arbitrary point
309e0 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 er. The impleme
309f0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ntation of the.*
30a00 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 * function can g
30a10 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 ain access to th
30a20 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 is pointer using
30a30 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
30a40 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ata()].)^.**.**
30a50 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 ^The sixth, seve
30a60 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 nth and eighth p
30a70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 arameters, xFunc
30a80 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e , xStep and xFin
30a90 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 al, are.** point
30aa0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 ers to C-languag
30ab0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 e functions that
30ac0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
30ad0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
30ae0 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 * aggregate. ^A
30af0 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
30b00 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
30b10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
30b20 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 f the xFunc.** c
30b30 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 allback only; NU
30b40 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 LL pointers must
30b50 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
30b60 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e e xStep and xFin
30b70 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 al.** parameters
30b80 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 . ^An aggregate
30b90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
30ba0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
30bb0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 ntation of xStep
30bc0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 .** and xFinal a
30bd0 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 nd NULL pointer
30be0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 must be passed f
30bf0 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 or xFunc. ^To de
30c00 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 lete an existing
30c10 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
30c20 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 or aggregate, p
30c30 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ass NULL pointer
30c40 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 s for all three
30c50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c function.** call
30c60 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 backs..**.** ^(I
30c70 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 f the ninth para
30c80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
30c90 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
30ca0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c _v2() is not NUL
30cb0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 L,.** then it is
30cc0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 destructor for
30cd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
30ce0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a data pointer. .*
30cf0 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 * The destructor
30d00 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
30d10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
30d20 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 deleted, either
30d30 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 by being.** ove
30d40 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 rloaded or when
30d50 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
30d60 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 nection closes.)
30d70 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 ^.** ^The destru
30d80 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 ctor is also inv
30d90 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c oked if the call
30da0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
30db0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
30dc0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 2() fails..** ^W
30dd0 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 hen the destruct
30de0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 or callback of t
30df0 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 he tenth paramet
30e00 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 er is invoked, i
30e10 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 t.** is passed a
30e20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
30e30 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 which is a copy
30e40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
30e50 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 ion data .** poi
30e60 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 nter which was t
30e70 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
30e80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 er to sqlite3_cr
30e90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
30ea0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ()..**.** ^It is
30eb0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 permitted to re
30ec0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 gister multiple
30ed0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
30ee0 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 of the same.** f
30ef0 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 unctions with th
30f00 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 e same name but
30f10 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 with either diff
30f20 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 ering numbers of
30f30 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 .** arguments or
30f40 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 differing prefe
30f50 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
30f60 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 ngs. ^SQLite wi
30f70 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d ll use.** the im
30f80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 plementation tha
30f90 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d t most closely m
30fa0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 atches the way i
30fb0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 n which the.** S
30fc0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 QL function is u
30fd0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f sed. ^A functio
30fe0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
30ff0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 with a non-nega
31000 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 tive.** nArg par
31010 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 ameter is a bett
31020 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
31030 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
31040 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 ntation with.**
31050 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e a negative nArg.
31060 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 ^A function wh
31070 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 ere the preferre
31080 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a d text encoding.
31090 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 ** matches the d
310a0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 atabase encoding
310b0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 is a better.**
310c0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
310d0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
310e0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 encoding is diff
310f0 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 erent. .** ^A f
31100 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
31110 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
31120 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e rence is between
31130 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 UTF16le and UTF
31140 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 16be.** is a clo
31150 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ser match than a
31160 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
31170 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
31180 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 ference is.** be
31190 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 tween UTF8 and U
311a0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 TF16..**.** ^Bui
311b0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 lt-in functions
311c0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 may be overloade
311d0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 d by new applica
311e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
311f0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 ctions..**.** ^A
31200 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
31210 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
31220 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 s permitted to c
31230 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c all other.** SQL
31240 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 ite interfaces.
31250 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 However, such c
31260 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a alls must not.**
31270 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
31280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e ase connection n
31290 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 or finalize or r
312a0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
312b0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 d.** statement i
312c0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 n which the func
312d0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
312e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
312f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
31300 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 e_function(. sq
31310 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
31320 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 st char *zFuncti
31330 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
31340 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
31350 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
31360 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
31370 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
31380 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
31390 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
313a0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
313b0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
313c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
313d0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
313e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
313f0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
31400 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
31410 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a ate_function16(.
31420 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 sqlite3 *db,.
31430 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 const void *zFu
31440 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e nctionName,. in
31450 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 t nArg,. int eT
31460 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a extRep,. void *
31470 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 pApp,. void (*x
31480 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f Func)(sqlite3_co
31490 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 ntext*,int,sqlit
314a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 e3_value**),. v
314b0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c oid (*xStep)(sql
314c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e ite3_context*,in
314d0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t,sqlite3_value*
314e0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 *),. void (*xFi
314f0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e nal)(sqlite3_con
31500 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 text*).);.SQLITE
31510 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
31520 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
31530 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a _v2(. sqlite3 *
31540 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 db,. const char
31550 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c *zFunctionName,
31560 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 . int nArg,. i
31570 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 nt eTextRep,. v
31580 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 oid *pApp,. voi
31590 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 d (*xFunc)(sqlit
315a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c e3_context*,int,
315b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 sqlite3_value**)
315c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 ,. void (*xStep
315d0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
315e0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
315f0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
31600 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 (*xFinal)(sqlite
31610 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 3_context*),. v
31620 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 oid(*xDestroy)(v
31630 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid*).);../*.**
31640 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 CAPI3REF: Text E
31650 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 ncodings.**.** T
31660 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 hese constant de
31670 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 fine integer cod
31680 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e es that represen
31690 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a t the various.**
316a0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 text encodings
316b0 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c supported by SQL
316c0 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
316d0 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 SQLITE_UTF8
316e0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
316f0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 SQLITE_UTF16LE
31700 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
31710 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 SQLITE_UTF16BE
31720 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 3.#define
31730 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 SQLITE_UTF16
31740 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 4 /* Us
31750 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 e native byte or
31760 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 der */.#define S
31770 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 QLITE_ANY
31780 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 5 /* Dep
31790 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 recated */.#defi
317a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f ne SQLITE_UTF16_
317b0 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a ALIGNED 8 /*
317c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
317d0 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a collation only *
317e0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
317f0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 F: Function Flag
31800 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f s.**.** These co
31810 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f nstants may be O
31820 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 Red together wit
31830 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
31840 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 E_UTF8 | preferr
31850 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
31860 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 ] as the fourth
31870 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b argument.** to [
31880 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
31890 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c unction()], [sql
318a0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
318b0 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a tion16()], or.**
318c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
318d0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e _function_v2()].
318e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
318f0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
31900 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 0x800../*.**
31910 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 CAPI3REF: Depre
31920 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a cated Functions.
31930 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a ** DEPRECATED.**
31940 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 .** These functi
31950 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 ons are [depreca
31960 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 ted]. In order
31970 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 to maintain.** b
31980 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
31990 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 bility with olde
319a0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 r code, these fu
319b0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 nctions continue
319c0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f .** to be suppo
319d0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 rted. However,
319e0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 new applications
319f0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a should avoid.**
31a00 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 the use of thes
31a10 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f e functions. To
31a20 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 help encourage
31a30 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a people to avoid.
31a40 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 ** using these f
31a50 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 unctions, we are
31a60 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 not going to te
31a70 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 ll you what they
31a80 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 do..*/.#ifndef
31a90 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 SQLITE_OMIT_DEPR
31aa0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 ECATED.SQLITE_AP
31ab0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
31ac0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
31ad0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 aggregate_count(
31ae0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
31af0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
31b00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
31b10 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 int sqlite3_expi
31b20 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 red(sqlite3_stmt
31b30 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
31b40 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
31b50 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 int sqlite3_tra
31b60 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 nsfer_bindings(s
31b70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 qlite3_stmt*, sq
31b80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
31b90 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
31ba0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 DEPRECATED int s
31bb0 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 qlite3_global_re
31bc0 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c cover(void);.SQL
31bd0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
31be0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 EPRECATED void s
31bf0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c qlite3_thread_cl
31c00 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c eanup(void);.SQL
31c10 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 ITE_API SQLITE_D
31c20 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
31c30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 lite3_memory_ala
31c40 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a rm(void(*)(void*
31c50 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 ,sqlite3_int64,i
31c60 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 nt),.
31c70 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a void*
31c80 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b ,sqlite3_int64);
31c90 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
31ca0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 API3REF: Obtaini
31cb0 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 ng SQL Function
31cc0 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 Parameter Values
31cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e .**.** The C-lan
31ce0 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 guage implementa
31cf0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 tion of SQL func
31d00 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
31d10 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 ates uses.** thi
31d20 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 s set of interfa
31d30 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 ce routines to a
31d40 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 ccess the parame
31d50 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a ter values on.**
31d60 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 the function or
31d70 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a aggregate..**.*
31d80 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 * The xFunc (for
31d90 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e scalar function
31da0 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 s) or xStep (for
31db0 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 aggregates) par
31dc0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 ameters.** to [s
31dd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
31de0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 nction()] and [s
31df0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
31e00 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 nction16()].** d
31e10 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 efine callbacks
31e20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 that implement t
31e30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 he SQL functions
31e40 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e and aggregates.
31e50 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 .** The 3rd para
31e60 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 meter to these c
31e70 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 allbacks is an a
31e80 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
31e90 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 to.** [protecte
31ea0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
31eb0 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 objects. There
31ec0 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 is one [sqlite3
31ed0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 _value] object f
31ee0 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d or.** each param
31ef0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 eter to the SQL
31f00 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 function. These
31f10 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
31f20 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 ed to.** extract
31f30 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 values from the
31f40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
31f50 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 objects..**.**
31f60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
31f70 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 ork only with [p
31f80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
31f90 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e _value] objects.
31fa0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 .** Any attempt
31fb0 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 to use these rou
31fc0 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 tines on an [unp
31fd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
31fe0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 _value].** objec
31ff0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 t results in und
32000 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e efined behavior.
32010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
32020 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 utines work just
32030 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 like the corres
32040 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 ponding [column
32050 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 access functions
32060 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 ].** except that
32070 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 these routines
32080 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b take a single [
32090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
320a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 3_value] object.
320b0 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 ** pointer inste
320c0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 ad of a [sqlite3
320d0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 _stmt*] pointer
320e0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 and an integer c
320f0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a olumn number..**
32100 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
32110 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 _value_text16()
32120 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 interface extrac
32130 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 ts a UTF-16 stri
32140 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 ng.** in the nat
32150 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f ive byte-order o
32160 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 f the host machi
32170 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c ne. ^The.** sql
32180 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
32190 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 6be() and sqlite
321a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
321b0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
321c0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 extract UTF-16
321d0 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 strings as big-e
321e0 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 ndian and little
321f0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 -endian respecti
32200 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 vely..**.** ^(Th
32210 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f e sqlite3_value_
32220 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 numeric_type() i
32230 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 nterface attempt
32240 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 s to apply.** nu
32250 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 meric affinity t
32260 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 o the value. Th
32270 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e is means that an
32280 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d attempt is.** m
32290 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ade to convert t
322a0 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 he value to an i
322b0 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 nteger or floati
322c0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a ng point. If.**
322d0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 such a conversi
322e0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 on is possible w
322f0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 ithout loss of i
32300 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f nformation (in o
32310 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 ther.** words, i
32320 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 f the value is a
32330 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f string that loo
32340 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 ks like a number
32350 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ).** then the co
32360 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 nversion is perf
32370 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 ormed. Otherwis
32380 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e no conversion
32390 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b occurs..** The [
323a0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
323b0 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 datatype] after
323c0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 conversion is r
323d0 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a eturned.)^.**.**
323e0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 Please pay part
323f0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e icular attention
32400 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 to the fact tha
32410 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 t the pointer re
32420 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
32430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
32440 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
32450 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f value_text()], o
32460 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 r.** [sqlite3_va
32470 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 lue_text16()] ca
32480 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 n be invalidated
32490 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 by a subsequent
324a0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
324b0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
324c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 ()], [sqlite3_va
324d0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 lue_bytes16()],
324e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
324f0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 ext()],.** or [s
32500 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
32510 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 t16()]..**.** Th
32520 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 ese routines mus
32530 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
32540 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
32550 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 as.** the SQL f
32560 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 unction that sup
32570 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 plied the [sqlit
32580 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d e3_value*] param
32590 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 eters..*/.SQLITE
325a0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
325b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 *sqlite3_value_b
325c0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 lob(sqlite3_valu
325d0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
325e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 int sqlite3_valu
325f0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f e_bytes(sqlite3_
32600 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
32610 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
32620 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 value_bytes16(sq
32630 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
32640 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 QLITE_API double
32650 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
32660 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 ouble(sqlite3_va
32670 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
32680 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 I int sqlite3_va
32690 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
326a0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
326b0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
326c0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 4 sqlite3_value_
326d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 int64(sqlite3_va
326e0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
326f0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 I const unsigned
32700 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
32710 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 alue_text(sqlite
32720 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
32730 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
32740 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f *sqlite3_value_
32750 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 text16(sqlite3_v
32760 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
32770 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
32780 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
32790 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 t16le(sqlite3_va
327a0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
327b0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
327c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
327d0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 16be(sqlite3_val
327e0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
327f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c int sqlite3_val
32800 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f ue_type(sqlite3_
32810 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f value*);.SQLITE_
32820 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
32830 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
32840 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
32850 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
32860 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 REF: Obtain Aggr
32870 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 egate Function C
32880 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 ontext.**.** Imp
32890 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 lementations of
328a0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
328b0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 nctions use this
328c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 .** routine to a
328d0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 llocate memory f
328e0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 or storing their
328f0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 state..**.** ^T
32900 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 he first time th
32910 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 e sqlite3_aggreg
32920 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
32930 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c routine is call
32940 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 ed .** for a par
32950 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 ticular aggregat
32960 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 e function, SQLi
32970 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 te.** allocates
32980 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 N of memory, zer
32990 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d oes out that mem
329a0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 ory, and returns
329b0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
329c0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e the new memory.
329d0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 ^On second and
329e0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 subsequent calls
329f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 to.** sqlite3_a
32a00 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
32a10 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 () for the same
32a20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
32a30 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 on instance,.**
32a40 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 the same buffer
32a50 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 is returned. Sq
32a60 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
32a70 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 context() is nor
32a80 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 mally.** called
32a90 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e once for each in
32aa0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 vocation of the
32ab0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 xStep callback a
32ac0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c nd then one.** l
32ad0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 ast time when th
32ae0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 e xFinal callbac
32af0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e k is invoked. ^
32b00 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 (When no rows ma
32b10 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 tch.** an aggreg
32b20 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 ate query, the x
32b30 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 Step() callback
32b40 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 of the aggregate
32b50 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 function.** imp
32b60 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e lementation is n
32b70 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 ever called and
32b80 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c xFinal() is call
32b90 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e ed exactly once.
32ba0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 .** In those cas
32bb0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 es, sqlite3_aggr
32bc0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
32bd0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 might be called
32be0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 for the.** first
32bf0 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 time from withi
32c00 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a n xFinal().)^.**
32c10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
32c20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
32c30 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 xt(C,N) routine
32c40 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
32c50 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 ointer .** when
32c60 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 first called if
32c70 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f N is less than o
32c80 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 r equal to zero
32c90 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a or if a memory.*
32ca0 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 * allocate error
32cb0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e occurs..**.** ^
32cc0 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 (The amount of s
32cd0 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 pace allocated b
32ce0 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 y sqlite3_aggreg
32cf0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
32d00 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 is.** determine
32d10 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d d by the N param
32d20 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 eter on first su
32d30 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 ccessful call.
32d40 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 Changing the.**
32d50 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 value of N in su
32d60 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f bsequent call to
32d70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
32d80 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 te_context() wit
32d90 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 hin.** the same
32da0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 aggregate functi
32db0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c on instance will
32dc0 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 not resize the
32dd0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
32de0 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 tion.)^ Within
32df0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 the xFinal callb
32e00 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f ack, it is custo
32e10 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e mary to set.** N
32e20 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 =0 in calls to s
32e30 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
32e40 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f _context(C,N) so
32e50 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 that no .** poi
32e60 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c ntless memory al
32e70 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e locations occur.
32e80 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 .**.** ^SQLite a
32e90 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 utomatically fre
32ea0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
32eb0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 located by .** s
32ec0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
32ed0 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 _context() when
32ee0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 the aggregate qu
32ef0 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a ery concludes..*
32f00 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 *.** The first p
32f10 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 arameter must be
32f20 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a a copy of the.*
32f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 * [sqlite3_conte
32f40 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f xt | SQL functio
32f50 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 n context] that
32f60 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 is the first par
32f70 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 ameter.** to the
32f80 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c xStep or xFinal
32f90 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e callback routin
32fa0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 e that implement
32fb0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a s the aggregate.
32fc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a ** function..**.
32fd0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 ** This routine
32fe0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 must be called f
32ff0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 rom the same thr
33000 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 ead in which.**
33010 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 the aggregate SQ
33020 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 L function is ru
33030 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 nning..*/.SQLITE
33040 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 _API void *sqlit
33050 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
33060 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e text(sqlite3_con
33070 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 text*, int nByte
33080 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 s);../*.** CAPI3
33090 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 REF: User Data F
330a0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a or Functions.**.
330b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
330c0 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 user_data() inte
330d0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
330e0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 copy of.** the p
330f0 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 ointer that was
33100 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 the pUserData pa
33110 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 rameter (the 5th
33120 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
33130 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
33140 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
33150 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
33160 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
33170 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
33180 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
33190 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
331a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
331b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
331c0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
331d0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
331e0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
331f0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
33200 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
33210 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
33220 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
33230 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
33240 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 id *sqlite3_user
33250 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f _data(sqlite3_co
33260 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
33270 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
33280 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f se Connection Fo
33290 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a r Functions.**.*
332a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
332b0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 ontext_db_handle
332c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 () interface ret
332d0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a urns a copy of.*
332e0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f * the pointer to
332f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
33300 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 onnection] (the
33310 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 1st parameter).*
33320 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * of the [sqlite
33330 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
33340 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c n()].** and [sql
33350 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
33360 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e tion16()] routin
33370 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c es that original
33380 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 ly.** registered
33390 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
333a0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f defined functio
333b0 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 n..*/.SQLITE_API
333c0 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 sqlite3 *sqlite
333d0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
333e0 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 dle(sqlite3_cont
333f0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
33400 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e PI3REF: Function
33410 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a Auxiliary Data.
33420 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
33430 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 tions may be use
33440 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 d by (non-aggreg
33450 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f ate) SQL functio
33460 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 ns to.** associa
33470 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 te metadata with
33480 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 argument values
33490 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 . If the same va
334a0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f lue is passed to
334b0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 .** multiple inv
334c0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
334d0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f same SQL functio
334e0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 n during query e
334f0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a xecution, under.
33500 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 ** some circumst
33510 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 ances the associ
33520 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 ated metadata ma
33530 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 y be preserved.
33540 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f An example.** o
33550 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 f where this mig
33560 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 ht be useful is
33570 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 in a regular-exp
33580 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 ression matching
33590 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 .** function. Th
335a0 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 e compiled versi
335b0 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 on of the regula
335c0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
335d0 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a be stored as.**
335e0 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 metadata associ
335f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 ated with the pa
33600 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a ttern string. .
33610 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 ** Then as long
33620 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 as the pattern s
33630 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 tring remains th
33640 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 e same,.** the c
33650 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 ompiled regular
33660 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 expression can b
33670 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 e reused on mult
33680 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 iple.** invocati
33690 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ons of the same
336a0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
336b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
336c0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
336d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 face returns a p
336e0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 ointer to the me
336f0 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 tadata.** associ
33700 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 ated by the sqli
33710 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
33720 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 ) function with
33730 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 the Nth argument
33740 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 .** value to the
33750 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33760 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e ined function. ^
33770 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d If there is no m
33780 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 etadata.** assoc
33790 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 iated with the f
337a0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 unction argument
337b0 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 , this sqlite3_g
337c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
337d0 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e erface.** return
337e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
337f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33800 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
33810 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 (C,N,P,X) interf
33820 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d ace saves P as m
33830 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 etadata for the
33840 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 N-th.** argument
33850 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
33860 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
33870 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 tion. ^Subseque
33880 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 nt.** calls to s
33890 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 qlite3_get_auxda
338a0 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 ta(C,N) return P
338b0 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 from the most r
338c0 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 ecent.** sqlite3
338d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
338e0 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 ,P,X) call if th
338f0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 e metadata is st
33900 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 ill valid or.**
33910 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 NULL if the meta
33920 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 data has been di
33930 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 scarded..** ^Aft
33940 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 er each call to
33950 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
33960 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 ata(C,N,P,X) whe
33970 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c re X is not NULL
33980 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c ,.** SQLite will
33990 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 invoke the dest
339a0 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 ructor function
339b0 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 X with parameter
339c0 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e P exactly.** on
339d0 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 ce, when the met
339e0 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 adata is discard
339f0 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 ed..** SQLite is
33a00 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 free to discard
33a10 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 the metadata at
33a20 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 any time, inclu
33a30 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c ding: <ul>.** <l
33a40 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 i> when the corr
33a50 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 esponding functi
33a60 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 on parameter cha
33a70 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e nges, or.** <li>
33a80 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 when [sqlite3_r
33a90 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
33aa0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
33ab0 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 is called for th
33ac0 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 e.** SQL st
33ad0 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c atement, or.** <
33ae0 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 li> when sqlite3
33af0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _set_auxdata() i
33b00 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 s invoked again
33b10 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 on the same para
33b20 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 meter, or.** <li
33b30 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 > during the ori
33b40 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 ginal sqlite3_se
33b50 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c t_auxdata() call
33b60 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a when a memory .
33b70 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 ** allocati
33b80 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e on error occurs.
33b90 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e </ul>)^.**.** N
33ba0 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c ote the last bul
33bb0 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 let in particula
33bc0 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 r. The destruct
33bd0 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 or X in .** sqli
33be0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
33bf0 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 C,N,P,X) might b
33c00 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 e called immedia
33c10 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 tely, before the
33c20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
33c30 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 auxdata() interf
33c40 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 ace even returns
33c50 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 . Hence sqlite3
33c60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a _set_auxdata().*
33c70 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c * should be call
33c80 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 ed near the end
33c90 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 of the function
33ca0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 implementation a
33cb0 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 nd the.** functi
33cc0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
33cd0 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b n should not mak
33ce0 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 e any use of P a
33cf0 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f fter.** sqlite3_
33d00 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 set_auxdata() ha
33d10 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a s been called..*
33d20 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 *.** ^(In practi
33d30 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 ce, metadata is
33d40 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 preserved betwee
33d50 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 n function calls
33d60 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e for.** function
33d70 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 parameters that
33d80 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d are compile-tim
33d90 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 e constants, inc
33da0 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a luding literal.*
33db0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 * values and [pa
33dc0 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 rameters] and ex
33dd0 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 pressions compos
33de0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
33df0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 .)^.**.** These
33e00 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
33e10 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
33e20 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 same thread in
33e30 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c which.** the SQL
33e40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e function is run
33e50 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ning..*/.SQLITE_
33e60 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
33e70 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_get_auxdata(sq
33e80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
33e90 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 int N);.SQLITE_A
33ea0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
33eb0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 set_auxdata(sqli
33ec0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
33ed0 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 t N, void*, void
33ee0 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a (*)(void*));...
33ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
33f00 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 Constants Defini
33f10 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 ng Special Destr
33f20 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a uctor Behavior.*
33f30 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 *.** These are s
33f40 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f pecial values fo
33f50 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 r the destructor
33f60 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 that is passed
33f70 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e in as the.** fin
33f80 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 al argument to r
33f90 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
33fa0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
33fb0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 b()]. ^If the d
33fc0 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 estructor.** arg
33fd0 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f ument is SQLITE_
33fe0 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 STATIC, it means
33ff0 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e that the conten
34000 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e t pointer is con
34010 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c stant.** and wil
34020 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 l never change.
34030 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 It does not nee
34040 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 d to be destroye
34050 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 d. ^The.** SQLI
34060 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c TE_TRANSIENT val
34070 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 ue means that th
34080 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c e content will l
34090 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a ikely change in.
340a0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 ** the near futu
340b0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 re and that SQLi
340c0 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 te should make i
340d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 ts own private c
340e0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f opy of.** the co
340f0 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 ntent before ret
34100 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 urning..**.** Th
34110 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 e typedef is nec
34120 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 essary to work a
34130 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 round problems i
34140 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b n certain.** C++
34150 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 compilers..*/.t
34160 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 ypedef void (*sq
34170 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 lite3_destructor
34180 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 _type)(void*);.#
34190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 define SQLITE_ST
341a0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 ATIC ((sqli
341b0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 te3_destructor_t
341c0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 ype)0).#define S
341d0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 QLITE_TRANSIENT
341e0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 ((sqlite3_dest
341f0 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a ructor_type)-1).
34200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34210 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 Setting The Res
34220 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 ult Of An SQL Fu
34230 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 nction.**.** The
34240 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
34250 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e used by the xFun
34260 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c c or xFinal call
34270 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d backs that.** im
34280 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 plement SQL func
34290 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
342a0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 ates. See.** [s
342b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
342c0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 nction()] and [s
342d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
342e0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 nction16()].** f
342f0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e or additional in
34300 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
34310 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 These functions
34320 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 work very much
34330 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 like the [parame
34340 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d ter binding] fam
34350 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 ily of.** functi
34360 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 ons used to bind
34370 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 values to host
34380 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 parameters in pr
34390 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
343a0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 s..** Refer to t
343b0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 he [SQL paramete
343c0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e r] documentation
343d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
343e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
343f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34400 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e result_blob() in
34410 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 terface sets the
34420 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 result from.**
34430 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
34440 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
34450 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 to be the BLOB w
34460 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 hose content is
34470 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 pointed.** to by
34480 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
34490 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 meter and which
344a0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 is N bytes long
344b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a where N is the.*
344c0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 * third paramete
344d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
344e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 lite3_result_zer
344f0 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 oblob() interfac
34500 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c es set the resul
34510 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
34520 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
34530 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
34540 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 BLOB containing
34550 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 all zero.** byt
34560 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 es and N bytes i
34570 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 n size, where N
34580 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 is the value of
34590 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
345a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r..**.** ^The sq
345b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 lite3_result_dou
345c0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ble() interface
345d0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 sets the result
345e0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 from.** an appli
345f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
34600 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 unction to be a
34610 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 floating point v
34620 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a alue specified.*
34630 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 * by its 2nd arg
34640 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ument..**.** ^Th
34650 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
34660 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
34670 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
34680 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a r16() functions.
34690 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 ** cause the imp
346a0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e lemented SQL fun
346b0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 ction to throw a
346c0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 n exception..**
346d0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 ^SQLite uses the
346e0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 string pointed
346f0 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 to by the.** 2nd
34700 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
34710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
34720 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f or() or sqlite3_
34730 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
34740 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 .** as the text
34750 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 of an error mess
34760 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e age. ^SQLite in
34770 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 terprets the err
34780 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 or.** message st
34790 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 ring from sqlite
347a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
347b0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 as UTF-8. ^SQLi
347c0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 te.** interprets
347d0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d the string from
347e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
347f0 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 error16() as UTF
34800 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a -16 in native.**
34810 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 byte order. ^I
34820 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
34830 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
34840 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a _result_error().
34850 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 ** or sqlite3_re
34860 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 sult_error16() i
34870 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 s negative then
34880 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 SQLite takes as
34890 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 the error.** mes
348a0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 sage all text up
348b0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 through the fir
348c0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 st zero characte
348d0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 r..** ^If the th
348e0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
348f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34900 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 error() or.** sq
34910 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
34920 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 or16() is non-ne
34930 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
34940 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 te takes that ma
34950 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 ny.** bytes (not
34960 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f characters) fro
34970 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 m the 2nd parame
34980 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 ter as the error
34990 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 message..** ^Th
349a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
349b0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c _error() and sql
349c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
349d0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 r16().** routine
349e0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 s make a private
349f0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 copy of the err
34a00 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 or message text
34a10 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 before.** they r
34a20 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 eturn. Hence, t
34a30 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 he calling funct
34a40 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 ion can dealloca
34a50 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 te or.** modify
34a60 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 the text after t
34a70 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f hey return witho
34a80 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 ut harm..** ^The
34a90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34aa0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e error_code() fun
34ab0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 ction changes th
34ac0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 e error code.**
34ad0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 returned by SQLi
34ae0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f te as a result o
34af0 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 f an error in a
34b00 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 function. ^By d
34b10 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 efault,.** the e
34b20 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c rror code is SQL
34b30 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 ITE_ERROR. ^A s
34b40 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 ubsequent call t
34b50 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 o sqlite3_result
34b60 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 _error().** or s
34b70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
34b80 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 ror16() resets t
34b90 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f he error code to
34ba0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a SQLITE_ERROR..*
34bb0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34bc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 3_result_error_t
34bd0 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 oobig() interfac
34be0 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
34bf0 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 to throw an.** e
34c00 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 rror indicating
34c10 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 that a string or
34c20 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e BLOB is too lon
34c30 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a g to represent..
34c40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
34c50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f e3_result_error_
34c60 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 nomem() interfac
34c70 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 e causes SQLite
34c80 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 to throw an.** e
34c90 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 rror indicating
34ca0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c that a memory al
34cb0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e location failed.
34cc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
34cd0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 te3_result_int()
34ce0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
34cf0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
34d00 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
34d10 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
34d20 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
34d30 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 e 32-bit signed
34d40 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
34d50 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
34d60 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e d argument..** ^
34d70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
34d80 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 lt_int64() inter
34d90 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
34da0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 turn value.** of
34db0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
34dc0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
34dd0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 n to be the 64-b
34de0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
34df0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e r.** value given
34e00 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 in the 2nd argu
34e10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ment..**.** ^The
34e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
34e30 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 null() interface
34e40 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
34e50 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
34e60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
34e70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
34e80 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
34e90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
34ea0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 ult_text(), sqli
34eb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
34ec0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6(),.** sqlite3_
34ed0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 result_text16le(
34ee0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 ), and sqlite3_r
34ef0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 esult_text16be()
34f00 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 interfaces.** s
34f10 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 et the return va
34f20 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 lue of the appli
34f30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
34f40 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a unction to be.**
34f50 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 a text string w
34f60 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e hich is represen
34f70 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 ted as UTF-8, UT
34f80 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 F-16 native byte
34f90 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 order,.** UTF-1
34fa0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 6 little endian,
34fb0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 or UTF-16 big e
34fc0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 ndian, respectiv
34fd0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ely..** ^SQLite
34fe0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 takes the text r
34ff0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 esult from the a
35000 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a pplication from.
35010 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d ** the 2nd param
35020 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 eter of the sqli
35030 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
35040 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
35050 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 ^If the 3rd para
35060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
35070 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
35080 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 * interfaces.**
35090 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 is negative, the
350a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 n SQLite takes r
350b0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 esult text from
350c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
350d0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 r.** through the
350e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 first zero char
350f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 acter..** ^If th
35100 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
35110 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
35120 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
35130 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e rfaces.** is non
35140 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
35150 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e as many bytes (n
35160 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f ot characters) o
35170 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f f the text.** po
35180 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
35190 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 2nd parameter ar
351a0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 e taken as the a
351b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
351c0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 ed.** function r
351d0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 esult. If the 3
351e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
351f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
35200 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 en it.** must be
35210 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 the byte offset
35220 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 into the string
35230 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 where the NUL t
35240 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a erminator would.
35250 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 ** appear if the
35260 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 string where NU
35270 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 L terminated. I
35280 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 f any NUL charac
35290 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e ters occur.** in
352a0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 the string at a
352b0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 byte offset tha
352c0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 t is less than t
352d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
352e0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 3rd.** parameter
352f0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c , then the resul
35300 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c ting string will
35310 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 contain embedde
35320 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a d NULs and the.*
35330 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 * result of expr
35340 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e essions operatin
35350 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 g on strings wit
35360 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 h embedded NULs
35370 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
35380 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
35390 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
353a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
353b0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
353c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
353d0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e lt_blob is a non
353e0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 -NULL pointer, t
353f0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 hen SQLite calls
35400 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f that.** functio
35410 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 n as the destruc
35420 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 tor on the text
35430 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 or BLOB result w
35440 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 hen it has.** fi
35450 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 nished using tha
35460 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 t result..** ^If
35470 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 the 4th paramet
35480 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
35490 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
354a0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a nterfaces or to.
354b0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
354c0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 t_blob is the sp
354d0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 ecial constant S
354e0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 QLITE_STATIC, th
354f0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 en SQLite.** ass
35500 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 umes that the te
35510 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
35520 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 t is in constant
35530 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
35540 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 not.** copy the
35550 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 content of the p
35560 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c arameter nor cal
35570 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f l a destructor o
35580 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a n the content.**
35590 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e when it has fin
355a0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 ished using that
355b0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 result..** ^If
355c0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 the 4th paramete
355d0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
355e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
355f0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 terfaces.** or s
35600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c qlite3_result_bl
35610 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 ob is the specia
35620 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 l constant SQLIT
35630 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 E_TRANSIENT.** t
35640 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 hen SQLite makes
35650 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 a copy of the r
35660 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 esult into space
35670 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a obtained from.*
35680 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
35690 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 malloc()] before
356a0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a it returns..**.
356b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
356c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 result_value() i
356d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 nterface sets th
356e0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 e result of.** t
356f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
35700 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
35710 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 to be a copy the
35720 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 .** [unprotected
35730 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
35740 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 object specified
35750 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 by the 2nd para
35760 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 meter. ^The.**
35770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
35780 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 alue() interface
35790 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 makes a copy of
357a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 the [sqlite3_va
357b0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 lue].** so that
357c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c the [sqlite3_val
357d0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e ue] specified in
357e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d the parameter m
357f0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 ay change or.**
35800 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 be deallocated a
35810 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 fter sqlite3_res
35820 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 ult_value() retu
35830 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d rns without harm
35840 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 ..** ^A [protect
35850 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
35860 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 ] object may alw
35870 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 ays be used wher
35880 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 e an.** [unprote
35890 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
358a0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 ue] object is re
358b0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 quired, so eithe
358c0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 r.** kind of [sq
358d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
358e0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 ect can be used
358f0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 with this interf
35900 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ace..**.** If th
35910 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
35920 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 called from wit
35930 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e hin the differen
35940 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e t thread.** than
35950 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e the one contain
35960 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 ing the applicat
35970 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
35980 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 tion that receiv
35990 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 ed.** the [sqlit
359a0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e e3_context] poin
359b0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 ter, the results
359c0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
359d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
359e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
359f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 t_blob(sqlite3_c
35a00 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
35a10 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
35a20 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
35a30 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
35a40 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c te3_result_doubl
35a50 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
35a60 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c t*, double);.SQL
35a70 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
35a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35a90 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 r(sqlite3_contex
35aa0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
35ab0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
35ac0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
35ad0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 esult_error16(sq
35ae0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
35af0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
35b00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
35b10 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
35b20 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
35b30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
35b40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
35b50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
35b60 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c _error_nomem(sql
35b70 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
35b80 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
35b90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
35ba0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 rror_code(sqlite
35bb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
35bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
35bd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
35be0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e _int(sqlite3_con
35bf0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c text*, int);.SQL
35c00 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
35c10 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 ite3_result_int6
35c20 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 4(sqlite3_contex
35c30 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 t*, sqlite3_int6
35c40 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
35c50 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
35c60 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f lt_null(sqlite3_
35c70 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 context*);.SQLIT
35c80 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
35c90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 e3_result_text(s
35ca0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35cb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e const char*, in
35cc0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
35cd0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
35ce0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
35cf0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
35d00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
35d10 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
35d20 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
35d30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
35d40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
35d50 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 xt16le(sqlite3_c
35d60 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
35d70 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
35d80 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
35d90 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
35da0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
35db0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 be(sqlite3_conte
35dc0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
35dd0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
35de0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
35df0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
35e00 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 esult_value(sqli
35e10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 te3_context*, sq
35e20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
35e30 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
35e40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 qlite3_result_ze
35e50 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 roblob(sqlite3_c
35e60 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b ontext*, int n);
35e70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
35e80 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c : Define New Col
35e90 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 lating Sequences
35ea0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
35eb0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d nctions add, rem
35ec0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 ove, or modify a
35ed0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 [collation] ass
35ee0 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
35ef0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
35f00 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
35f10 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 ied as the first
35f20 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
35f30 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 ^The name of th
35f40 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 e collation is a
35f50 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a UTF-8 string.**
35f60 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 for sqlite3_cre
35f70 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 ate_collation()
35f80 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 and sqlite3_crea
35f90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
35fa0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 ).** and a UTF-1
35fb0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 6 string in nati
35fc0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f ve byte order fo
35fd0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 r sqlite3_create
35fe0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a _collation16()..
35ff0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 ** ^Collation na
36000 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 mes that compare
36010 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 equal according
36020 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 to [sqlite3_str
36030 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 nicmp()] are.**
36040 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 considered to be
36050 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a the same name..
36060 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 **.** ^(The thir
36070 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 d argument (eTex
36080 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e tRep) must be on
36090 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e e of the constan
360a0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c ts:.** <ul>.** <
360b0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 li> [SQLITE_UTF8
360c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
360d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 TE_UTF16LE],.**
360e0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 <li> [SQLITE_UTF
360f0 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 16BE],.** <li> [
36100 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f SQLITE_UTF16], o
36110 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 r.** <li> [SQLIT
36120 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
36130 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ..** </ul>)^.**
36140 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 ^The eTextRep ar
36150 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 gument determine
36160 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f s the encoding o
36170 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 f strings passed
36180 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 .** to the colla
36190 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 ting function ca
361a0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 llback, xCallbac
361b0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 k..** ^The [SQLI
361c0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 TE_UTF16] and [S
361d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
361e0 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 NED] values for
361f0 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 eTextRep.** forc
36200 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 e strings to be
36210 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 UTF16 with nativ
36220 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
36230 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 ^The [SQLITE_UT
36240 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c F16_ALIGNED] val
36250 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 ue for eTextRep
36260 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 forces strings t
36270 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e o begin.** on an
36280 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 even byte addre
36290 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ss..**.** ^The f
362a0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 ourth argument,
362b0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c pArg, is an appl
362c0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
362d0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73 nter that is pas
362e0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 sed.** through a
362f0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
36300 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c ment to the coll
36310 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
36320 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e allback..**.** ^
36330 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 The fifth argume
36340 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 nt, xCallback, i
36350 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
36360 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
36370 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 ction..** ^Multi
36380 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 ple collating fu
36390 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 nctions can be r
363a0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
363b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 the same name bu
363c0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 t.** with differ
363d0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72 ent eTextRep par
363e0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 ameters and SQLi
363f0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 te will use whic
36400 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f hever.** functio
36410 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c n requires the l
36420 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 east amount of d
36430 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 ata transformati
36440 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 on..** ^If the x
36450 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e Callback argumen
36460 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 t is NULL then t
36470 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
36480 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 ction is.** dele
36490 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 ted. ^When all
364a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
364b0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 ons having the s
364c0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c ame name are del
364d0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f eted,.** that co
364e0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f llation is no lo
364f0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a nger usable..**.
36500 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e ** ^The collatin
36510 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 g function callb
36520 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
36530 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 ith a copy of th
36540 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 e pArg .** appli
36550 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
36560 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f ter and with two
36570 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 strings in the
36580 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
36590 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 ed.** by the eTe
365a0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 xtRep argument.
365b0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
365c0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 unction must ret
365d0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 urn an.** intege
365e0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 r that is negati
365f0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 ve, zero, or pos
36600 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 itive.** if the
36610 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 first string is
36620 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c less than, equal
36630 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 to, or greater
36640 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c than the second,
36650 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 .** respectively
36660 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 . A collating f
36670 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 unction must alw
36680 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
36690 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 ame answer.** gi
366a0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 ven the same inp
366b0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 uts. If two or
366c0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 more collating f
366d0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 unctions are reg
366e0 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 istered.** to th
366f0 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e e same collation
36700 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 name (using dif
36710 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 ferent eTextRep
36720 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c values) then all
36730 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e .** must give an
36740 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 equivalent answ
36750 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 er when invoked
36760 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 with equivalent
36770 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 strings..** The
36780 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
36790 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 on must obey the
367a0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 following prope
367b0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a rties for all.**
367c0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 strings A, B, a
367d0 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e nd C:.**.** <ol>
367e0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
367f0 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c then B==A..** <
36800 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 li> If A==B and
36810 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a B==C then A==C..
36820 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b ** <li> If A<
36830 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a B THEN B>A..*
36840 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 * <li> If A<B
36850 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e and B<C then
36860 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c A<C..** </ol
36870 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c >.**.** If a col
36880 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
36890 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 fails any of the
368a0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e above constrain
368b0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 ts and that.** c
368c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
368d0 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 n is registered
368e0 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 and used, then
368f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 the behavior of
36900 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 SQLite.** is und
36910 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
36920 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 he sqlite3_creat
36930 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 e_collation_v2()
36940 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
36950 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
36960 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 tion().** with t
36970 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 he addition that
36980 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 the xDestroy ca
36990 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
369a0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a d on pArg when.*
369b0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 * the collating
369c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 function is dele
369d0 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 ted..** ^Collati
369e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ng functions are
369f0 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 deleted when th
36a00 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 ey are overridde
36a10 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 n by later.** ca
36a20 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 lls to the colla
36a30 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 tion creation fu
36a40 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 nctions or when
36a50 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
36a60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
36a70 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 closed using [sq
36a80 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a lite3_close()]..
36a90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 **.** ^The xDest
36aa0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 roy callback is
36ab0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 <u>not</u> calle
36ac0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c d if the .** sql
36ad0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
36ae0 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 ation_v2() funct
36af0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c ion fails. Appl
36b00 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e ications that in
36b10 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
36b20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
36b30 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e _v2() with a non
36b40 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 -NULL xDestroy a
36b50 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a rgument should .
36b60 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ** check the ret
36b70 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 urn code and dis
36b80 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c pose of the appl
36b90 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
36ba0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 nter.** themselv
36bb0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 es rather than e
36bc0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 xpecting SQLite
36bd0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 to deal with it
36be0 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 for them..** Thi
36bf0 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 s is different f
36c00 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 rom every other
36c10 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
36c20 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 . The inconsist
36c30 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f ency .** is unfo
36c40 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e rtunate but cann
36c50 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 ot be changed wi
36c60 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 thout breaking b
36c70 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d ackwards .** com
36c80 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a patibility..**.*
36c90 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 * See also: [sq
36ca0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
36cb0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 needed()] and [s
36cc0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
36cd0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f _needed16()]..*/
36ce0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
36cf0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
36d00 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 ollation(. sqli
36d10 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 te3*, . const c
36d20 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 har *zName, . i
36d30 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 nt eTextRep, .
36d40 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e void *pArg,. in
36d50 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 t(*xCompare)(voi
36d60 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
36d70 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 d*,int,const voi
36d80 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 d*).);.SQLITE_AP
36d90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
36da0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
36db0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 2(. sqlite3*, .
36dc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
36dd0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
36de0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
36df0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
36e00 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
36e10 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
36e20 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 const void*),.
36e30 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 void(*xDestroy)(
36e40 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 void*).);.SQLITE
36e50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
36e60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
36e70 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c n16(. sqlite3*,
36e80 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a . const void *
36e90 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 zName,. int eTe
36ea0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a xtRep, . void *
36eb0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f pArg,. int(*xCo
36ec0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 mpare)(void*,int
36ed0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 ,const void*,int
36ee0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b ,const void*).);
36ef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
36f00 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 : Collation Need
36f10 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a ed Callbacks.**.
36f20 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 ** ^To avoid hav
36f30 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 ing to register
36f40 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 all collation se
36f50 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 quences before a
36f60 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e database.** can
36f70 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 be used, a sing
36f80 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 le callback func
36f90 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 tion may be regi
36fa0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a stered with the.
36fb0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
36fc0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 nection] to be i
36fd0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 nvoked whenever
36fe0 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c an undefined col
36ff0 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e lation.** sequen
37000 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a ce is required..
37010 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 **.** ^If the fu
37020 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 nction is regist
37030 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 ered using the s
37040 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
37050 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a _needed() API,.*
37060 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 * then it is pas
37070 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 sed the names of
37080 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 undefined colla
37090 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 tion sequences a
370a0 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 s strings.** enc
370b0 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e oded in UTF-8. ^
370c0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 If sqlite3_colla
370d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 tion_needed16()
370e0 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 is used,.** the
370f0 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 names are passed
37100 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 as UTF-16 in ma
37110 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 chine native byt
37120 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 e order..** ^A c
37130 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 all to either fu
37140 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 nction replaces
37150 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c the existing col
37160 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 lation-needed ca
37170 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 llback..**.** ^(
37180 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
37190 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 k is invoked, th
371a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
371b0 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 passed is a cop
371c0 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f y.** of the seco
371d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 nd argument to s
371e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
371f0 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 _needed() or.**
37200 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
37210 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 n_needed16(). T
37220 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
37230 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 nt is the databa
37240 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
37250 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
37260 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 ument is one of
37270 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
37280 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
37290 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 .** or [SQLITE_U
372a0 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 TF16LE], indicat
372b0 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 ing the most des
372c0 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 irable form of t
372d0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 he collation.**
372e0 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f sequence functio
372f0 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 n required. The
37300 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
37310 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
37320 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 the.** required
37330 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
37340 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 nce.)^.**.** The
37350 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
37360 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 on should regist
37370 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 er the desired c
37380 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a ollation using.*
37390 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 * [sqlite3_creat
373a0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 e_collation()],
373b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
373c0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 collation16()],
373d0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 or.** [sqlite3_c
373e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
373f0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 v2()]..*/.SQLITE
37400 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
37410 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 _collation_neede
37420 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a d(. sqlite3*, .
37430 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 void*, . void
37440 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
37450 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 3*,int eTextRep,
37460 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a const char*).);.
37470 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
37480 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e qlite3_collation
37490 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c _needed16(. sql
374a0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c ite3*, . void*,
374b0 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a . void(*)(void*
374c0 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 ,sqlite3*,int eT
374d0 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 extRep,const voi
374e0 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 d*).);..#ifdef S
374f0 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a QLITE_HAS_CODEC.
37500 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 /*.** Specify th
37510 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 e key for an enc
37520 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e rypted database.
37530 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 This routine s
37540 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c hould be.** call
37550 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 ed right after s
37560 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a qlite3_open()..*
37570 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f *.** The code to
37580 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 implement this
37590 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c API is not avail
375a0 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c able in the publ
375b0 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 ic release.** of
375c0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 SQLite..*/.SQLI
375d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
375e0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 e3_key(. sqlite
375f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 3 *db,
37600 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
37610 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 base to be rekey
37620 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f ed */. const vo
37630 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b id *pKey, int nK
37640 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 ey /* The ke
37650 79 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 y */.);.SQLITE_A
37660 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b PI int sqlite3_k
37670 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 ey_v2(. sqlite3
37680 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
37690 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
376a0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
376b0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 d */. const cha
376c0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 r *zDbName,
376d0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
376e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f the database */
376f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 . const void *p
37700 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 Key, int nKey
37710 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a /* The key */.
37720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 );../*.** Change
37730 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f the key on an o
37740 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 pen database. I
37750 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 f the current da
37760 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a tabase is not.**
37770 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 encrypted, this
37780 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e routine will en
37790 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e crypt it. If pN
377a0 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 ew==0 or nNew==0
377b0 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 , the.** databas
377c0 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a e is decrypted..
377d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 **.** The code t
377e0 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 o implement this
377f0 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 API is not avai
37800 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 lable in the pub
37810 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f lic release.** o
37820 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c f SQLite..*/.SQL
37830 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
37840 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c te3_rekey(. sql
37850 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
37860 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
37870 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
37880 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 keyed */. const
37890 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 void *pKey, int
378a0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 nKey /* The
378b0 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53 new key */.);.S
378c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
378d0 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 0a lite3_rekey_v2(.
378e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
378f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37900 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 /* Database to
37910 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 be rekeyed */.
37920 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e const char *zDbN
37930 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f ame, /
37940 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 * Name of the da
37950 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 tabase */. cons
37960 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e t void *pKey, in
37970 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 t nKey /* Th
37980 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a e new key */.);.
37990 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 ./*.** Specify t
379a0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 he activation ke
379b0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61 y for a SEE data
379c0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a base. Unless .*
379d0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e * activated, non
379e0 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75 e of the SEE rou
379f0 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e tines will work.
37a00 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
37a10 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 oid sqlite3_acti
37a20 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 vate_see(. cons
37a30 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 t char *zPassPhr
37a40 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 ase /* Ac
37a50 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 tivation phrase
37a60 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 */.);.#endif..#i
37a70 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 fdef SQLITE_ENAB
37a80 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 LE_CEROD./*.** S
37a90 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 pecify the activ
37aa0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 ation key for a
37ab0 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 CEROD database.
37ac0 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 Unless .** acti
37ad0 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 vated, none of t
37ae0 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 he CEROD routine
37af0 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a s will work..*/.
37b00 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
37b10 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 sqlite3_activate
37b20 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 _cerod(. const
37b30 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 char *zPassPhras
37b40 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 e /* Acti
37b50 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f vation phrase */
37b60 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a .);.#endif../*.*
37b70 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 * CAPI3REF: Susp
37b80 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f end Execution Fo
37b90 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a r A Short Time.*
37ba0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
37bb0 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f _sleep() functio
37bc0 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 n causes the cur
37bd0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 rent thread to s
37be0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e uspend execution
37bf0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 .** for at least
37c00 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c a number of mil
37c10 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 liseconds specif
37c20 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d ied in its param
37c30 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 eter..**.** If t
37c40 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 he operating sys
37c50 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 tem does not sup
37c60 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 port sleep reque
37c70 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c sts with.** mill
37c80 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 isecond time res
37c90 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 olution, then th
37ca0 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 e time will be r
37cb0 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 ounded up to.**
37cc0 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f the nearest seco
37cd0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f nd. The number o
37ce0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f f milliseconds o
37cf0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 f sleep actually
37d00 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 .** requested fr
37d10 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 om the operating
37d20 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 system is retur
37d30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ned..**.** ^SQLi
37d40 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 te implements th
37d50 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 is interface by
37d60 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 calling the xSle
37d70 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f ep().** method o
37d80 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 f the default [s
37d90 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 qlite3_vfs] obje
37da0 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 ct. If the xSle
37db0 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f ep() method.** o
37dc0 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 f the default VF
37dd0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 S is not impleme
37de0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 nted correctly,
37df0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 or not implement
37e00 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 ed at.** all, th
37e10 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
37e20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 of sqlite3_sleep
37e30 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 () may deviate f
37e40 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 rom the descript
37e50 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 ion.** in the pr
37e60 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
37e70 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
37e80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 int sqlite3_sle
37e90 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ep(int);../*.**
37ea0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f CAPI3REF: Name O
37eb0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c f The Folder Hol
37ec0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 ding Temporary F
37ed0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 iles.**.** ^(If
37ee0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 this global vari
37ef0 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 able is made to
37f00 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
37f10 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 g which is.** th
37f20 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 e name of a fold
37f30 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 er (a.k.a. direc
37f40 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 tory), then all
37f50 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a temporary files.
37f60 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 ** created by SQ
37f70 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 Lite when using
37f80 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 a built-in [sqli
37f90 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a te3_vfs | VFS].*
37fa0 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 * will be placed
37fb0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f in that directo
37fc0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 ry.)^ ^If this
37fd0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 variable.** is a
37fe0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 NULL pointer, t
37ff0 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f hen SQLite perfo
38000 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 rms a search for
38010 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a an appropriate.
38020 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
38030 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a e directory..**.
38040 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 ** It is not saf
38050 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 e to read or mod
38060 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c ify this variabl
38070 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f e in more than o
38080 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 ne.** thread at
38090 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e a time. It is n
380a0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 ot safe to read
380b0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 or modify this v
380c0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 ariable.** if a
380d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
380e0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 tion] is being u
380f0 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 sed at the same
38100 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 time in a separa
38110 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a te.** thread..**
38120 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 It is intended
38130 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 that this variab
38140 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a le be set once.*
38150 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f * as part of pro
38160 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 cess initializat
38170 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 ion and before a
38180 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
38190 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ace.** routines
381a0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
381b0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 and that this v
381c0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 ariable remain u
381d0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 nchanged.** ther
381e0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eafter..**.** ^T
381f0 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
38200 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
38210 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 may modify this
38220 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 variable and ca
38230 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 use.** it to poi
38240 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 nt to memory obt
38250 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
38260 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 te3_malloc]. ^F
38270 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 urthermore,.** t
38280 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
38290 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
382a0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 always assumes
382b0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a that any string.
382c0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 ** that this var
382d0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 iable points to
382e0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 is held in memor
382f0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
38300 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c .** [sqlite3_mal
38310 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 loc] and the pra
38320 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 gma may attempt
38330 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d to free that mem
38340 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 ory.** using [sq
38350 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 lite3_free]..**
38360 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 Hence, if this v
38370 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 ariable is modif
38380 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 ied directly, ei
38390 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 ther it should b
383a0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f e.** made NULL o
383b0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 r made to point
383c0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
383d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
383e0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 _malloc].** or e
383f0 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 lse the use of t
38400 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 he [temp_store_d
38410 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d irectory pragma]
38420 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 should be avoid
38430 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 ed..**.** <b>Not
38440 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e e to Windows Run
38450 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 time users:</b>
38460 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 The temporary d
38470 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 irectory must be
38480 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f set.** prior to
38490 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
384a0 33 5f 6f 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 3_open] or [sqli
384b0 74 65 33 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f te3_open_v2]. O
384c0 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 therwise, variou
384d0 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 s.** features th
384e0 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 at require the u
384f0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 se of temporary
38500 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 files may fail.
38510 20 48 65 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 Here is an.** e
38520 78 61 6d 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f xample of how to
38530 20 64 6f 20 74 68 69 73 20 75 73 69 6e 67 20 43 do this using C
38540 2b 2b 20 77 69 74 68 20 74 68 65 20 57 69 6e 64 ++ with the Wind
38550 6f 77 73 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a ows Runtime:.**.
38560 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
38570 70 72 65 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 pre>.** LPCWSTR
38580 7a 50 61 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a zPath = Windows:
38590 3a 53 74 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 :Storage::Applic
385a0 61 74 69 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 ationData::Curre
385b0 6e 74 2d 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 nt->.**
385c0 20 20 20 54 65 6d 70 6f 72 61 72 79 46 6f 6c 64 TemporaryFold
385d0 65 72 2d 3e 50 61 74 68 2d 3e 44 61 74 61 28 29 er->Path->Data()
385e0 3b 0a 2a 2a 20 63 68 61 72 20 7a 50 61 74 68 42 ;.** char zPathB
385f0 75 66 26 23 39 31 3b 4d 41 58 5f 50 41 54 48 20 uf[MAX_PATH
38600 2b 20 31 26 23 39 33 3b 3b 0a 2a 2a 20 6d 65 6d + 1];.** mem
38610 73 65 74 28 7a 50 61 74 68 42 75 66 2c 20 30 2c set(zPathBuf, 0,
38620 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75 66 sizeof(zPathBuf
38630 29 29 3b 0a 2a 2a 20 57 69 64 65 43 68 61 72 54 ));.** WideCharT
38640 6f 4d 75 6c 74 69 42 79 74 65 28 43 50 5f 55 54 oMultiByte(CP_UT
38650 46 38 2c 20 30 2c 20 7a 50 61 74 68 2c 20 2d 31 F8, 0, zPath, -1
38660 2c 20 7a 50 61 74 68 42 75 66 2c 20 73 69 7a 65 , zPathBuf, size
38670 6f 66 28 7a 50 61 74 68 42 75 66 29 2c 0a 2a 2a of(zPathBuf),.**
38680 20 26 6e 62 73 70 3b 20 20 20 20 20 4e 55 4c 4c NULL
38690 2c 20 4e 55 4c 4c 29 3b 0a 2a 2a 20 73 71 6c 69 , NULL);.** sqli
386a0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
386b0 72 79 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 ry = sqlite3_mpr
386c0 69 6e 74 66 28 22 25 73 22 2c 20 7a 50 61 74 68 intf("%s", zPath
386d0 42 75 66 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c Buf);.** </pre><
386e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2f 0a /blockquote>.*/.
386f0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
38700 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 E_EXTERN char *s
38710 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
38720 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ctory;../*.** CA
38730 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 PI3REF: Name Of
38740 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 The Folder Holdi
38750 6e 67 20 44 61 74 61 62 61 73 65 20 46 69 6c 65 ng Database File
38760 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 s.**.** ^(If thi
38770 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c s global variabl
38780 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6