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 37 2e 31 35 2e 31 22 0a 23 64 65 66 69 6e 65 .7.15.1".#define
1030: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
1040: 4e 55 4d 42 45 52 20 33 30 30 37 30 31 35 0a 23 NUMBER 3007015.#
1050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f define SQLITE_SO
1060: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 URCE_ID "20
1070: 31 32 2d 31 32 2d 31 39 20 32 30 3a 33 39 3a 31 12-12-19 20:39:1
1080: 30 20 36 62 38 35 62 37 36 37 64 30 66 66 37 39 0 6b85b767d0ff79
1090: 37 35 31 34 36 31 35 36 61 39 39 61 64 36 37 33 75146156a99ad673
10a0: 66 32 63 31 61 32 33 33 31 38 22 0a 0a 2f 2a 0a f2c1a23318"../*.
10b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
10c0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 -Time Library Ve
10d0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a rsion Numbers.**
10e0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
10f0: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 e3_version, sqli
1100: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a te3_sourceid.**.
1110: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 ** These interfa
1120: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 ces provide the
1130: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
1140: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f as the [SQLITE_
1150: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 VERSION],.** [SQ
1160: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
1170: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 BER], and [SQLIT
1180: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 E_SOURCE_ID] C p
1190: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
11a0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 os.** but are as
11b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
11c0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 e library instea
11d0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 d of the header
11e0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 file. ^(Cautiou
11f0: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 s.** programmers
1200: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 might include a
1210: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e ssert() statemen
1220: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c ts in their appl
1230: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 ication to.** ve
1240: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 rify that values
1250: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
1260: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 se interfaces ma
1270: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 tch the macros i
1280: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c n.** the header,
1290: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 and thus insure
12a0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 that the applic
12b0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 ation is.** comp
12c0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 iled with matchi
12d0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 ng library and h
12e0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a eader files..**.
12f0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1300: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 pre>.** assert(
1310: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1320: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c on_number()==SQL
1330: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
1340: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 ER );.** assert(
1350: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f strcmp(sqlite3_
1360: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 sourceid(),SQLIT
1370: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 E_SOURCE_ID)==0
1380: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 );.** assert( st
1390: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 rcmp(sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 version(),SQLITE
13b0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a _VERSION)==0 );.
13c0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
13d0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e quote>)^.**.** ^
13e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 The sqlite3_vers
13f0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
1400: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 stant contains t
1410: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 he text of [SQLI
1420: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d TE_VERSION].** m
1430: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 acro. ^The sqli
1440: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
1450: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
1460: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
1470: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c he.** to the sql
1480: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 ite3_version[] s
1490: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 tring constant.
14a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 The sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e version().** fun
14c0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 ction is provide
14d0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c d for use in DLL
14e0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 s since DLL user
14f0: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 s usually do not
1500: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 have.** direct
1510: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 access to string
1520: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 constants withi
1530: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 n the DLL. ^The
1540: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 .** sqlite3_libv
1550: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 ersion_number()
1560: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1570: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 an integer equa
1580: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f l to.** [SQLITE_
1590: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e VERSION_NUMBER].
15a0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^The sqlite3_s
15b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 ourceid() functi
15c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 on returns .** a
15d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 pointer to a st
15e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 ring constant wh
15f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 ose value is the
1600: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a same as the .**
1610: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f [SQLITE_SOURCE_
1620: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ID] C preprocess
1630: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 or macro..**.**
1640: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
1650: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 e_version()] and
1660: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f [sqlite_source_
1670: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 id()]..*/.SQLITE
1680: 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 _API SQLITE_EXTE
1690: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 RN const char sq
16a0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b lite3_version[];
16b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
16c0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
16d0: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 libversion(void)
16e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
16f0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
1700: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b _sourceid(void);
1710: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
1720: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1730: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b on_number(void);
1740: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1750: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
1760: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f ry Compilation O
1770: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 ptions Diagnosti
1780: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 cs.**.** ^The sq
1790: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
17a0: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 ion_used() funct
17b0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 ion returns 0 or
17c0: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 1 .** indicatin
17d0: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 g whether the sp
17e0: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 ecified option w
17f0: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a as defined at .*
1800: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 * compile time.
1810: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 ^The SQLITE_ pr
1820: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 efix may be omit
1830: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a ted from the .**
1840: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 option name pas
1850: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 sed to sqlite3_c
1860: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1870: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 d(). .**.** ^Th
1880: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c e sqlite3_compil
1890: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 eoption_get() fu
18a0: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 nction allows it
18b0: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 erating.** over
18c0: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 the list of opti
18d0: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 ons that were de
18e0: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 fined at compile
18f0: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 time by.** retu
1900: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 rning the N-th c
1910: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 ompile time opti
1920: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 on string. ^If
1930: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 N is out of rang
1940: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f e,.** sqlite3_co
1950: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
1960: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c ) returns a NULL
1970: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
1980: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 SQLITE_ .** pref
1990: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 ix is omitted fr
19a0: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 om any strings r
19b0: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 eturned by .** s
19c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
19d0: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a tion_get()..**.*
19e0: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 * ^Support for t
19f0: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 he diagnostic fu
1a00: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f nctions sqlite3_
1a10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
1a20: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 ed().** and sqli
1a30: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1a40: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f n_get() may be o
1a50: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 mitted by specif
1a60: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 ying the .** [SQ
1a70: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
1a80: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f EOPTION_DIAGS] o
1a90: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 ption at compile
1aa0: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 time..**.** See
1ab0: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 also: SQL funct
1ac0: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d ions [sqlite_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
1ae0: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
1af0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f e_compileoption_
1b00: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b get()] and the [
1b10: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 compile_options
1b20: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e pragma]..*/.#ifn
1b30: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
1b40: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 COMPILEOPTION_DI
1b50: 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 AGS.SQLITE_API i
1b60: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 nt sqlite3_compi
1b70: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f leoption_used(co
1b80: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 nst char *zOptNa
1b90: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 me);.SQLITE_API
1ba0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
1bb0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1bc0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 n_get(int N);.#e
1bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
1be0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 3REF: Test To Se
1bf0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 e If The Library
1c00: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a Is Threadsafe.*
1c10: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1c20: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 3_threadsafe() f
1c30: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1c40: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 zero if and only
1c50: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 if.** SQLite wa
1c60: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1c70: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d mutexing code om
1c80: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 itted due to the
1c90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
1ca0: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d ADSAFE] compile-
1cb0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e time option bein
1cc0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a g set to 0..**.*
1cd0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 * SQLite can be
1ce0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 compiled with or
1cf0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 without mutexes
1d00: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b . When.** the [
1d10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1d20: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f E] C preprocesso
1d30: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 r macro is 1 or
1d40: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
1d50: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
1d60: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1d70: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1d80: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1d90: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1da0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1db0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1dc0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1dd0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1de0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1df0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1e00: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
1e10: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
1e20: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
1e30: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
1e40: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
1e50: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
1e60: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1e70: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1e80: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1e90: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1ea0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1eb0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1ec0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1ed0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1ee0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
1ef0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f t behavior is fo
1f00: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 r mutexes to be
1f10: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 enabled..**.** T
1f20: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
1f30: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 n be used by an
1f40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d application to m
1f50: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 ake sure that th
1f60: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 e.** version of
1f70: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 SQLite that it i
1f80: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 s linking agains
1f90: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 t was compiled w
1fa0: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 ith.** the desir
1fb0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 ed setting of th
1fc0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
1fd0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a SAFE] macro..**.
1fe0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
1ff0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f e only reports o
2000: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 n the compile-ti
2010: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 me mutex setting
2020: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
2030: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 TE_THREADSAFE] f
2040: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 lag. If SQLite
2050: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
2060: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 .** SQLITE_THREA
2070: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 DSAFE=1 or =2 th
2080: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 en mutexes are e
2090: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
20a0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 t but.** can be
20b0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c fully or partial
20c0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e ly disabled usin
20d0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c g a call to [sql
20e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a ite3_config()].*
20f0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 * with the verbs
2100: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
2110: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b SINGLETHREAD], [
2120: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
2130: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f LTITHREAD],.** o
2140: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
2150: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 _MUTEX]. ^(The
2160: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
2170: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 the.** sqlite3_t
2180: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 hreadsafe() func
2190: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 tion shows only
21a0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 the compile-time
21b0: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 setting of.** t
21c0: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f hread safety, no
21d0: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 t any run-time c
21e0: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 hanges to that s
21f0: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a etting made by.*
2200: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 * sqlite3_config
2210: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 (). In other wor
2220: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ds, the return v
2230: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
2240: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 3_threadsafe().*
2250: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 * is unchanged b
2260: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 y calls to sqlit
2270: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a e3_config().)^.*
2280: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 *.** See the [th
2290: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f reading mode] do
22a0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
22b0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
22c0: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 mation..*/.SQLIT
22d0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
22e0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 3_threadsafe(voi
22f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
2300: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
2310: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a nnection Handle.
2320: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 ** KEYWORDS: {da
2330: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2340: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e n} {database con
2350: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 nections}.**.**
2360: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 Each open SQLite
2370: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 database is rep
2380: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f resented by a po
2390: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
23a0: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f ance of.** the o
23b0: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 paque structure
23c0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e named "sqlite3".
23d0: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 It is useful t
23e0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 o think of an sq
23f0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 lite3.** pointer
2400: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 as an object.
2410: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 The [sqlite3_ope
2420: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
2430: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a pen16()], and.**
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
2450: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 2()] interfaces
2460: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 are its construc
2470: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 tors, and [sqlit
2480: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 e3_close()].** a
2490: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
24a0: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 e_v2()] are its
24b0: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 destructors. Th
24c0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 ere are many oth
24d0: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 er.** interfaces
24e0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 (such as.** [sq
24f0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
2510: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
2520: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2530: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
2540: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 ] to name but th
2550: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 ree) that are me
2560: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 thods on an.** s
2570: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a qlite3 object..*
2580: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
2590: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 sqlite3 sqlite3
25a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
25b0: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 F: 64-Bit Intege
25c0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f r Types.** KEYWO
25d0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 RDS: sqlite_int6
25e0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 4 sqlite_uint64.
25f0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
2600: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d ere is no cross-
2610: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 platform way to
2620: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 specify 64-bit i
2630: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 nteger types.**
2640: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 SQLite includes
2650: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d typedefs for 64-
2660: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 bit signed and u
2670: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 nsigned integers
2680: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
2690: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
26a0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 lite3_uint64 are
26b0: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 the preferred t
26c0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e ype definitions.
26d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 .** The sqlite_i
26e0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
26f0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 uint64 types are
2700: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
2710: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
2720: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a atibility only..
2730: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2740: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
2750: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 ite_int64 types
2760: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
2770: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 r values.** betw
2780: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 een -92233720368
2790: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 54775808 and +92
27a0: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 2337203685477580
27b0: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 7 inclusive. ^T
27c0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 he.** sqlite3_ui
27d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
27e0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e uint64 types can
27f0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 store integer v
2800: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 alues .** betwee
2810: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 n 0 and +1844674
2820: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 4073709551615 in
2830: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 clusive..*/.#ifd
2840: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
2850: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 TYPE. typedef S
2860: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
2870: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2880: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2890: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 d SQLITE_INT64_T
28a0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 YPE sqlite_uint6
28b0: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 4;.#elif defined
28c0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 (_MSC_VER) || de
28d0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 fined(__BORLANDC
28e0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f __). typedef __
28f0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 int64 sqlite_int
2900: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
2910: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 signed __int64 s
2920: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
2930: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f lse. typedef lo
2940: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
2950: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
2960: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e def unsigned lon
2970: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
2980: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 e_uint64;.#endif
2990: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
29a0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e int64 sqlite3_in
29b0: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c t64;.typedef sql
29c0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 ite_uint64 sqlit
29d0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a e3_uint64;../*.*
29e0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 * If compiling f
29f0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 or a processor t
2a00: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 hat lacks floati
2a10: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 ng point support
2a20: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 ,.** substitute
2a30: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 integer for floa
2a40: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 ting-point..*/.#
2a50: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 ifdef SQLITE_OMI
2a60: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 T_FLOATING_POINT
2a70: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 .# define double
2a80: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 sqlite3_int64.#
2a90: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
2aa0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 I3REF: Closing A
2ab0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
2ac0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tion.**.** ^The
2ad0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
2ae0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 and sqlite3_clos
2af0: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 e_v2() routines
2b00: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a are destructors.
2b10: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 ** for the [sqli
2b20: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 te3] object..**
2b30: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 ^Calls to sqlite
2b40: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 3_close() and sq
2b50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2b60: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f return SQLITE_O
2b70: 4b 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c K if.** the [sql
2b80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 ite3] object is
2b90: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 successfully des
2ba0: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 troyed and all a
2bb0: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 ssociated.** res
2bc0: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c ources are deall
2bd0: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 ocated..**.** ^I
2be0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 onnection is ass
2c00: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 ociated with unf
2c10: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 inalized prepare
2c20: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 d.** statements
2c30: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 or unfinished sq
2c40: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a lite3_backup obj
2c50: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 ects then sqlite
2c60: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 3_close().** wil
2c70: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 l leave the data
2c80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2c90: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 open and return
2ca0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a [SQLITE_BUSY]..*
2cb0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c * ^If sqlite3_cl
2cc0: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c ose_v2() is call
2cd0: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 ed with unfinali
2ce0: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 zed prepared sta
2cf0: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 tements.** and u
2d00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 nfinished sqlite
2d10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 3_backups, then
2d20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2d30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a nection becomes.
2d40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 ** an unusable "
2d50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 zombie" which wi
2d60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ll automatically
2d70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
2d80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 when the.** last
2d90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2da0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 ent is finalized
2db0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c or the last sql
2dc0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a ite3_backup is.*
2dd0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 * finished. The
2de0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
2df0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
2e00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
2e10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c e with.** host l
2e20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 anguages that ar
2e30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 e garbage collec
2e40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 ted, and where t
2e50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 he order in whic
2e60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 h.** destructors
2e70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 are called is a
2e80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 rbitrary..**.**
2e90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
2ea0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e uld [sqlite3_fin
2eb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
2ec0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 ] all [prepared
2ed0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 statements],.**
2ee0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c [sqlite3_blob_cl
2ef0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c ose | close] all
2f00: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
2f10: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 and .** [sqlite
2f20: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 3_backup_finish
2f30: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 | finish] all [s
2f40: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
2f50: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 bjects associate
2f60: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 d.** with the [s
2f70: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 qlite3] object p
2f80: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 rior to attempti
2f90: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 ng to close the
2fa0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 object. ^If.**
2fb0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
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 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
3f50: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
3f60: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 d by.** the
3f70: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
3f80: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3f90: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 while sqlite3_e
3fa0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 xec() is running
3fb0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 ..** <li> The ap
3fc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
3fd0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 ot modify the SQ
3fe0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
3ff0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 passed into.**
4000: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 the 2nd par
4010: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
4020: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 3_exec() while s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
4040: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 running..** </u
4050: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l>.*/.SQLITE_API
4060: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 int sqlite3_exe
4070: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 c(. sqlite3*,
4080: 20 20 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: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
40b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
40c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 har *sql,
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40e0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
40f0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 evaluated */.
4100: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 int (*callback)(
4110: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a void*,int,char**
4120: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 ,char**), /* Ca
4130: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
4140: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. 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: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 /* 1st argument
4180: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 to callback */.
4190: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 char **errmsg
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 /* E
41c0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
41d0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a here */.);../*.
41e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
41f0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ult Codes.** KEY
4200: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b WORDS: SQLITE_OK
4210: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 {error code} {e
4220: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b rror codes}.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 EYWORDS: {result
4240: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 code} {result c
4250: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 odes}.**.** Many
4260: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e SQLite function
4270: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 s return an inte
4280: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ger result code
4290: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f from the set sho
42a0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 wn.** here in or
42b0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 der to indicate
42c0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 success or failu
42d0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 re..**.** New er
42e0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 ror codes may be
42f0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
4300: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
4310: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ite..**.** See a
4320: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 lso: [SQLITE_IOE
4330: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 RR_READ | extend
4340: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d ed result codes]
4350: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 ,.** [sqlite3_vt
4360: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 ab_on_conflict()
4370: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 ] [SQLITE_ROLLBA
4380: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 CK | result code
4390: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s]..*/.#define S
43a0: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 QLITE_OK
43b0: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 0 /* Succes
43c0: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f sful result */./
43d0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 * beginning-of-e
43e0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 rror-codes */.#d
43f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 efine SQLITE_ERR
4400: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a OR 1 /*
4410: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 SQL error or mi
4420: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a ssing database *
4430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4440: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 _INTERNAL 2
4450: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f /* Internal lo
4460: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c gic error in SQL
4470: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ite */.#define S
4480: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 QLITE_PERM
4490: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 3 /* Access
44a0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 permission deni
44b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
44c0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 LITE_ABORT
44d0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 4 /* Callbac
44e0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 k routine reques
44f0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a ted an abort */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
4510: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 USY 5
4520: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
4530: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a file is locked *
4540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4550: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 _LOCKED 6
4560: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 /* A table in
4570: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
4580: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
4590: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 e SQLITE_NOMEM
45a0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 7 /* A m
45b0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a alloc() failed *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
45d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 _READONLY 8
45e0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 /* Attempt to
45f0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 write a readonly
4600: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
4610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
4620: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 RRUPT 9 /*
4630: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e Operation termin
4640: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
4650: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 interrupt()*/.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4670: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a RR 10 /*
4680: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 Some kind of di
4690: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 sk I/O error occ
46a0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 urred */.#define
46b0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 SQLITE_CORRUPT
46c0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 11 /* The
46d0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d database disk im
46e0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 age is malformed
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 TE_NOTFOUND 1
4710: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 2 /* Unknown o
4720: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 pcode in sqlite3
4730: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 _file_control()
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4750: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 E_FULL 13
4760: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 /* Insertion
4770: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 failed because d
4780: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 atabase is full
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
47a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 E_CANTOPEN 14
47b0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 /* Unable to
47c0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
47d0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
47e0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f e SQLITE_PROTOCO
47f0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 L 15 /* Dat
4800: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f abase lock proto
4810: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 col error */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 fine SQLITE_EMPT
4830: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 Y 16 /*
4840: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 Database is empt
4850: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4860: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 ITE_SCHEMA
4870: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 17 /* The data
4880: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
4890: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ged */.#define S
48a0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 QLITE_TOOBIG
48b0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 18 /* String
48c0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 or BLOB exceeds
48d0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 size limit */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
48f0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f NSTRAINT 19 /
4900: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 * Abort due to c
4910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
4920: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ion */.#define S
4930: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 QLITE_MISMATCH
4940: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 20 /* Data t
4950: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a ype mismatch */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
4970: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 ISUSE 21
4980: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 /* Library used
4990: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 incorrectly */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
49b0: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f LFS 22 /
49c0: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 * Uses OS featur
49d0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 es not supported
49e0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 on host */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 ine SQLITE_AUTH
4a00: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 23 /* A
4a10: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e uthorization den
4a20: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
4a30: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 QLITE_FORMAT
4a40: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 24 /* Auxili
4a50: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 ary database for
4a60: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 mat error */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 fine SQLITE_RANG
4a80: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 E 25 /*
4a90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
4aa0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 sqlite3_bind ou
4ab0: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 t of range */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 efine SQLITE_NOT
4ad0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a ADB 26 /*
4ae0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 File opened tha
4af0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 t is not a datab
4b00: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 ase file */.#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 ine SQLITE_ROW
4b20: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 100 /* s
4b30: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
4b40: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 s another row re
4b50: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ady */.#define S
4b60: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 QLITE_DONE
4b70: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 101 /* sqlite
4b80: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 3_step() has fin
4b90: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 ished executing
4ba0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 */./* end-of-err
4bb0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a or-codes */../*.
4bc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 ** CAPI3REF: Ext
4bd0: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
4be0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
4bf0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 {extended error
4c00: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 code} {extended
4c10: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 error codes}.**
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d ded result code}
4c40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c {extended resul
4c50: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 t codes}.**.** I
4c60: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f n its default co
4c70: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c nfiguration, SQL
4c80: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 ite API routines
4c90: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 return one of 2
4ca0: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 6 integer.** [SQ
4cb0: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 LITE_OK | result
4cc0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 codes]. Howeve
4cd0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 r, experience ha
4ce0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e s shown that man
4cf0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 y of.** these re
4d00: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 sult codes are t
4d10: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 oo coarse-graine
4d20: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 d. They do not
4d30: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 provide as.** mu
4d40: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ch information a
4d50: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 bout problems as
4d60: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
4d70: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 ht like. In an
4d80: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 effort to.** add
4d90: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 ress this, newer
4da0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
4db0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 ite (version 3.3
4dc0: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e .8 and later) in
4dd0: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 clude.** support
4de0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
4df0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 result codes tha
4e00: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 t provide more d
4e10: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 etailed informat
4e20: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 ion.** about err
4e30: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 ors. The extende
4e40: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
4e50: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 re enabled or di
4e60: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 sabled.** on a p
4e70: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e er database conn
4e80: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 ection basis usi
4e90: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
4ea0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
4eb0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e lt_codes()] API.
4ec0: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 .**.** Some of t
4ed0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 he available ext
4ee0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
4ef0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 es are listed he
4f00: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 re..** One may e
4f10: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 xpect the number
4f20: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 of extended res
4f30: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 ult codes will b
4f40: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 e expand.** over
4f50: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 time. Software
4f60: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e that uses exten
4f70: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
4f80: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a should expect.*
4f90: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 * to see new res
4fa0: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 ult codes in fut
4fb0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
4fc0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
4fd0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 e SQLITE_OK resu
4fe0: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 lt code will nev
4ff0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 er be extended.
5000: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a It will always.
5010: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 ** be exactly ze
5020: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ro..*/.#define S
5030: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
5040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 (S
5050: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5060: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5070: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
5080: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 _READ (SQ
5090: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c LITE_IOERR | (2<
50a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
50b0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 ITE_IOERR_WRITE
50c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
50d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c ITE_IOERR | (3<<
50e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
50f0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 TE_IOERR_FSYNC
5100: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
5110: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 TE_IOERR | (4<<8
5120: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5130: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e E_IOERR_DIR_FSYN
5140: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 C (SQLIT
5150: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 E_IOERR | (5<<8)
5160: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5170: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 _IOERR_TRUNCATE
5180: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5190: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 _IOERR | (6<<8))
51a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
51b0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 IOERR_FSTAT
51c0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
51d0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a IOERR | (7<<8)).
51e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
51f0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 OERR_UNLOCK
5200: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5210: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 OERR | (8<<8)).#
5220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5230: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 ERR_RDLOCK
5240: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5250: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 ERR | (9<<8)).#d
5260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5270: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 RR_DELETE
5280: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5290: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 RR | (10<<8)).#d
52a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
52b0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 RR_BLOCKED
52c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
52d0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 RR | (11<<8)).#d
52e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
52f0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 RR_NOMEM
5300: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5310: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 RR | (12<<8)).#d
5320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5330: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 RR_ACCESS
5340: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5350: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 RR | (13<<8)).#d
5360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5370: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 RR_CHECKRESERVED
5380: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 LOCK (SQLITE_IOE
5390: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 RR | (14<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
53b0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 RR_LOCK
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
53d0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 RR | (15<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
53f0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 RR_CLOSE
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 RR | (16<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5430: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 RR_DIR_CLOSE
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 RR | (17<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5470: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 RR_SHMOPEN
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 RR | (18<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
54b0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 RR_SHMSIZE
54c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 RR | (19<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
54f0: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 RR_SHMLOCK
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5510: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 RR | (20<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5530: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 RR_SHMMAP
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5550: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 RR | (21<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5570: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 RR_SEEK
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5590: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 RR | (22<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
55b0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 RR_DELETE_NOENT
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
55d0: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 RR | (23<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
55f0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 KED_SHAREDCACHE
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 (SQLITE_LOC
5610: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 KED | (1<<8)).#
5620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
5630: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 SY_RECOVERY
5640: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 (SQLITE_BU
5650: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a SY | (1<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5670: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 ANTOPEN_NOTEMPDI
5680: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 R (SQLITE_C
5690: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 ANTOPEN | (1<<8)
56a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
56b0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 _CANTOPEN_ISDIR
56c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
56d0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c _CANTOPEN | (2<<
56e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
56f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c TE_CANTOPEN_FULL
5700: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 PATH (SQLI
5710: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 TE_CANTOPEN | (3
5720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5730: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 LITE_CORRUPT_VTA
5740: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 B (SQ
5750: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 LITE_CORRUPT | (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5770: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 QLITE_READONLY_R
5780: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 ECOVERY (S
5790: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
57a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
57c0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 _CANTLOCK
57d0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
57e0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
57f0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f ne SQLITE_ABORT_
5800: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 ROLLBACK
5810: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 (SQLITE_ABORT
5820: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a | (2<<8))../*.**
5830: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
5840: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
5850: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 perations.**.**
5860: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 These bit values
5870: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
5880: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 r use in the.**
5890: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
58a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
58b0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
58c0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 ce and.** in the
58d0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
58e0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
58f0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
5900: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
5920: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
5930: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0001 /* Ok for
5940: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5950: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5960: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
5970: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
5980: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0002 /* Ok for
5990: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
59a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
59b0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
59c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
59d0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0004 /* Ok for
59e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
59f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
5a10: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
5a20: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0008 /* VFS onl
5a30: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5a40: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
5a50: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
5a60: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0010 /* VFS onl
5a70: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5a80: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f ITE_OPEN_AUTOPRO
5a90: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 XY 0x0000
5aa0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0020 /* VFS onl
5ab0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5ac0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 ITE_OPEN_URI
5ad0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5ae0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0040 /* Ok for
5af0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5b00: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5b10: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 ITE_OPEN_MEMORY
5b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5b30: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0080 /* Ok for
5b40: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5b50: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5b60: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
5b70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5b80: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0100 /* VFS onl
5b90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5ba0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
5bb0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5bc0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0200 /* VFS onl
5bd0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5be0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
5bf0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
5c00: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0400 /* VFS onl
5c10: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5c20: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
5c30: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
5c40: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0800 /* VFS onl
5c50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5c60: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
5c70: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
5c80: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 1000 /* VFS onl
5c90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5ca0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
5cb0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
5cc0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 2000 /* VFS onl
5cd0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5ce0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
5cf0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
5d00: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 4000 /* VFS onl
5d10: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
5d20: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
5d30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
5d40: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 8000 /* Ok for
5d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5d60: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5d70: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
5d80: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 EX 0x0001
5d90: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
5da0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5db0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5dc0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
5dd0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 ACHE 0x0002
5de0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
5df0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5e00: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5e10: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
5e20: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 CACHE 0x0004
5e30: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
5e40: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5e50: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
5e60: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 ITE_OPEN_WAL
5e70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 0x0008
5e80: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0000 /* VFS onl
5e90: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 y */../* Reserve
5ea0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 d:
5eb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 0x00F
5ec0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 00000 */../*.**
5ed0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
5ee0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
5ef0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
5f00: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
5f10: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
5f20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
5f30: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
5f40: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
5f50: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
5f60: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 tor of these.**
5f70: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
5f80: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
5f90: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
5fa0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
5fb0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
5fc0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
5fd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
5fe0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
5ff0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
6000: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6010: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
6020: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
6030: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
6040: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
6050: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6060: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
6070: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
6080: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
6090: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
60a0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
60b0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
60c0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
60d0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
60e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
60f0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
6100: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
6110: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
6120: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
6130: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
6140: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
6150: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
6160: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
6170: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
6180: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
6190: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
61a0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
61b0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
61c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
61d0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
61e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
61f0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
6200: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
6210: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
6220: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
6230: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 e(). The SQLITE
6240: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
6250: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 _OVERWRITE prope
6260: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
6270: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 * after reboot f
6280: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 ollowing a crash
6290: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 or power loss,
62a0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 the only bytes i
62b0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 n a.** file that
62c0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 were written at
62d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
62e0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 level might hav
62f0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 e changed.** and
6300: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 that adjacent b
6310: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 ytes, even bytes
6320: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
6330: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 sector are.** g
6340: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 uaranteed to be
6350: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 unchanged..*/.#d
6360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6370: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 AP_ATOMIC
6380: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6390: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 0001.#define SQL
63a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
63b0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 512
63c0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 0x00000002.#def
63d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
63e0: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 _ATOMIC1K
63f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
6400: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 04.#define SQLIT
6410: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b E_IOCAP_ATOMIC2K
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
6430: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e x00000008.#defin
6440: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
6450: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 TOMIC4K
6460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
6470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 IOCAP_ATOMIC8K
6490: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
64a0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 0000020.#define
64b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
64c0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 MIC16K
64d0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 0x00000040.#
64e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
64f0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 CAP_ATOMIC32K
6500: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6510: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 00080.#define SQ
6520: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6530: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 C64K
6540: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 0x00000100.#de
6550: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6560: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 P_SAFE_APPEND
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
6580: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 200.#define SQLI
6590: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
65a0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 IAL
65b0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 0x00000400.#defi
65c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
65d0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e UNDELETABLE_WHEN
65e0: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 _OPEN 0x0000080
65f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6600: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
6610: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 _OVERWRITE 0x
6620: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 00001000../*.**
6630: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c CAPI3REF: File L
6640: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a ocking Levels.**
6650: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
6660: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 one of these int
6670: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
6680: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 he second.** arg
6690: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 ument to calls i
66a0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 t makes to the x
66b0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f Lock() and xUnlo
66c0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 ck() methods.**
66d0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 of an [sqlite3_i
66e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
66f0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t..*/.#define SQ
6700: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 LITE_LOCK_NONE
6710: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
6720: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 e SQLITE_LOCK_SH
6730: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 ARED 1.#d
6740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6750: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20 K_RESERVED
6760: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
6770: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 _LOCK_PENDING
6780: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 3.#define SQ
6790: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
67a0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a IVE 4../*.**
67b0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 CAPI3REF: Synch
67c0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 ronization Type
67d0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e Flags.**.** When
67e0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 SQLite invokes
67f0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 the xSync() meth
6800: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c od of an.** [sql
6810: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6820: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 object it uses
6830: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 a combination of
6840: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 .** these intege
6850: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
6860: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e second argument.
6870: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
6880: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
6890: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 ONLY flag is use
68a0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 d, it means that
68b0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 the.** sync ope
68c0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 ration only need
68d0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 s to flush data
68e0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e to mass storage.
68f0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 Inode.** infor
6900: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 mation need not
6910: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 be flushed. If t
6920: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
6930: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a ts of the flag.*
6940: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 * equal SQLITE_S
6950: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 YNC_NORMAL, that
6960: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f means to use no
6970: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d rmal fsync() sem
6980: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 antics..** If th
6990: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 e lower four bit
69a0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 s equal SQLITE_S
69b0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d YNC_FULL, that m
69c0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d eans.** to use M
69d0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 ac OS X style fu
69e0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f llsync instead o
69f0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a f fsync()..**.**
6a00: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 Do not confuse
6a10: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f the SQLITE_SYNC_
6a20: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
6a30: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 E_SYNC_FULL flag
6a40: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 s.** with the [P
6a50: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
6a60: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 s]=NORMAL and [P
6a70: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
6a80: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 s]=FULL.** setti
6a90: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 ngs. The [synch
6aa0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 ronous pragma] d
6ab0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 etermines when c
6ac0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 alls to the.** x
6ad0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 Sync VFS method
6ae0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 occur and applie
6af0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f s uniformly acro
6b00: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 ss all platforms
6b10: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f ..** The SQLITE_
6b20: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
6b30: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
6b40: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 flags determine
6b50: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 how.** energeti
6b60: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 c or rigorous or
6b70: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 forceful the sy
6b80: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 nc operations ar
6b90: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 e and.** only ma
6ba0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 ke a difference
6bb0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 on Mac OSX for t
6bc0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 he default SQLit
6bd0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 e code..** (Thir
6be0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c d-party VFS impl
6bf0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 ementations migh
6c00: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 t also make the
6c10: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 distinction.** b
6c20: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 etween SQLITE_SY
6c30: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
6c40: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 LITE_SYNC_FULL,
6c50: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a but among the.**
6c60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
6c70: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 ms natively supp
6c80: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c orted by SQLite,
6c90: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a only Mac OSX.**
6ca0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 cares about the
6cb0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f difference.).*/
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6cd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 SYNC_NORMAL
6ce0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 0x00002.#defi
6cf0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 ne SQLITE_SYNC_F
6d00: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 ULL 0x0
6d10: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 0003.#define SQL
6d20: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
6d30: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a Y 0x00010..
6d40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
6d50: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 OS Interface Ope
6d60: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a n File Handle.**
6d70: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f .** An [sqlite3_
6d80: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 file] object rep
6d90: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 resents an open
6da0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 file in the .**
6db0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f [sqlite3_vfs | O
6dc0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 S interface laye
6dd0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 r]. Individual
6de0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 OS interface.**
6df0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
6e00: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 will.** want to
6e10: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 subclass this ob
6e20: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e ject by appendin
6e30: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 g additional fie
6e40: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 lds.** for their
6e50: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 own use. The p
6e60: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 Methods entry is
6e70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
6e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f .** [sqlite3_io_
6e90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
6ea0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 that defines met
6eb0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d hods for perform
6ec0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 ing.** I/O opera
6ed0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 tions on the ope
6ee0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 n file..*/.typed
6ef0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
6f00: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 3_file sqlite3_f
6f10: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ile;.struct sqli
6f20: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e te3_file {. con
6f30: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 st struct sqlite
6f40: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 3_io_methods *pM
6f50: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 ethods; /* Meth
6f60: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 ods for an open
6f70: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a file */.};../*.*
6f80: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
6f90: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 nterface File Vi
6fa0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 rtual Methods Ob
6fb0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 ject.**.** Every
6fc0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 file opened by
6fd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
6fe0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 .xOpen] method p
6ff0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b opulates an.** [
7000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7010: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 ject (or, more c
7020: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c ommonly, a subcl
7030: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 ass of the.** [s
7040: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a qlite3_file] obj
7050: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e ect) with a poin
7060: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
7070: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
7080: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 t..** This objec
7090: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 t defines the me
70a0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 thods used to pe
70b0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 rform various op
70c0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 erations.** agai
70d0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c nst the open fil
70e0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 e represented by
70f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
7100: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a le] object..**.*
7110: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 * If the [sqlite
7120: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
7130: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c hod sets the sql
7140: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7150: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 ds element .** t
7160: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 o a non-NULL poi
7170: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 nter, then the s
7180: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7190: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a s.xClose method.
71a0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ** may be invoke
71b0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 d even if the [s
71c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
71d0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 ] reported that
71e0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a it failed. The.
71f0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 ** only way to p
7200: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f revent a call to
7210: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e xClose followin
7220: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 g a failed [sqli
7230: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a te3_vfs.xOpen].*
7240: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 * is for the [sq
7250: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
7260: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 to set the sqli
7270: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
7280: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 s element.** to
7290: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 NULL..**.** The
72a0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
72b0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f o xSync may be o
72c0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 ne of [SQLITE_SY
72d0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a NC_NORMAL] or.**
72e0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 [SQLITE_SYNC_FU
72f0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 LL]. The first
7300: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f choice is the no
7310: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a rmal fsync()..**
7320: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 The second choi
7330: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 ce is a Mac OS X
7340: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e style fullsync.
7350: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 The [SQLITE_SY
7360: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 NC_DATAONLY].**
7370: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 flag may be ORed
7380: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 in to indicate
7390: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 that only the da
73a0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a ta of the file.*
73b0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e * and not its in
73c0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 ode needs to be
73d0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 synced..**.** Th
73e0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
73f0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 to xLock() and
7400: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e xUnlock() are on
7410: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 e of.** <ul>.**
7420: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 <li> [SQLITE_LOC
7430: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e K_NONE],.** <li>
7440: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 [SQLITE_LOCK_SH
7450: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b ARED],.** <li> [
7460: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
7470: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b RVED],.** <li> [
7480: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
7490: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e ING], or.** <li>
74a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
74b0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 CLUSIVE]..** </u
74c0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e l>.** xLock() in
74d0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b creases the lock
74e0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 . xUnlock() decr
74f0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a eases the lock..
7500: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 ** The xCheckRes
7510: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 ervedLock() meth
7520: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 od checks whethe
7530: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 r any database c
7540: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 onnection,.** ei
7550: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f ther in this pro
7560: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 cess or in some
7570: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 other process, i
7580: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 s holding a RESE
7590: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 RVED,.** PENDING
75a0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c , or EXCLUSIVE l
75b0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e ock on the file.
75c0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 It returns tru
75d0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c e.** if such a l
75e0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 ock exists and f
75f0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a alse otherwise..
7600: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 **.** The xFileC
7610: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 ontrol() method
7620: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 is a generic int
7630: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f erface that allo
7640: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 ws custom.** VFS
7650: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
7660: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e to directly con
7670: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c trol an open fil
7680: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b e using the.** [
7690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
76a0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 trol()] interfac
76b0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 e. The second "
76c0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 op" argument is
76d0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 an.** integer op
76e0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 code. The third
76f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 argument is a g
7700: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 eneric pointer i
7710: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f ntended to.** po
7720: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 int to a structu
7730: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 re that may cont
7740: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 ain arguments or
7750: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 space in which
7760: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 to.** write retu
7770: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 rn values. Pote
7780: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 ntial uses for x
7790: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 FileControl() mi
77a0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 ght be.** functi
77b0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c ons to enable bl
77c0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 ocking locks wit
77d0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 h timeouts, to c
77e0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 hange the.** loc
77f0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 king strategy (f
7800: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 or example to us
7810: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 e dot-file locks
7820: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a ), to inquire.**
7830: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 about the statu
7840: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 s of a lock, or
7850: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c to break stale l
7860: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 ocks. The SQLit
7870: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 e.** core reserv
7880: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c es all opcodes l
7890: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 ess than 100 for
78a0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a its own use..**
78b0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c A [SQLITE_FCNTL
78c0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 _LOCKSTATE | lis
78d0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 t of opcodes] le
78e0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 ss than 100 is a
78f0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 vailable..** App
7900: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 lications that d
7910: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 efine a custom x
7920: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
7930: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 od should use op
7940: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 codes.** greater
7950: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f than 100 to avo
7960: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 id conflicts. V
7970: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
7980: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ns should.** ret
7990: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 urn [SQLITE_NOTF
79a0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 OUND] for file c
79b0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 ontrol opcodes t
79c0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
79d0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a ** recognize..**
79e0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 .** The xSectorS
79f0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 ize() method ret
7a00: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 urns the sector
7a10: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 size of the.** d
7a20: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 evice that under
7a30: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 lies the file.
7a40: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 The sector size
7a50: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 is the.** minimu
7a60: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e m write that can
7a70: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 be performed wi
7a80: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 thout disturbing
7a90: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 .** other bytes
7aa0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 in the file. Th
7ab0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
7ac0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 eristics().** me
7ad0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 thod returns a b
7ae0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 it vector descri
7af0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f bing behaviors o
7b00: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 f the.** underly
7b10: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a ing device:.**.*
7b20: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
7b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7b40: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 MIC].** <li> [SQ
7b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
7b60: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C512].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7b80: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC1K].** <li> [S
7b90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7ba0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC2K].** <li> [S
7bb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7bc0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC4K].** <li> [S
7bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7be0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 IC8K].** <li> [S
7bf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7c00: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC16K].** <li> [
7c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
7c20: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC32K].** <li>
7c30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
7c40: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC64K].** <li>
7c50: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 [SQLITE_IOCAP_S
7c60: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c AFE_APPEND].** <
7c70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
7c80: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a P_SEQUENTIAL].**
7c90: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 </ul>.**.** The
7ca0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
7cb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 OMIC property me
7cc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 ans that all wri
7cd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 tes of.** any si
7ce0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 ze are atomic.
7cf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
7d00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 _ATOMICnnn value
7d10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 s.** mean that w
7d20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 rites of blocks
7d30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 that are nnn byt
7d40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a es in size and.*
7d50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f * are aligned to
7d60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 an address whic
7d70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 h is an integer
7d80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e multiple of.** n
7d90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 nn are atomic.
7da0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
7db0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c _SAFE_APPEND val
7dc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 ue means.** that
7dd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 when data is ap
7de0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 pended to a file
7df0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 , the data is ap
7e00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 pended.** first
7e10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 then the size of
7e20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 the file is ext
7e30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 ended, never the
7e40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 other.** way ar
7e50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 ound. The SQLIT
7e60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
7e70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e AL property mean
7e80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d s that.** inform
7e90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e ation is written
7ea0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 to disk in the
7eb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 same order as ca
7ec0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 lls.** to xWrite
7ed0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 ()..**.** If xRe
7ee0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c ad() returns SQL
7ef0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
7f00: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 READ it must als
7f10: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 o fill.** in the
7f20: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 unread portions
7f30: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 of the buffer w
7f40: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 ith zeros. A VF
7f50: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 S that.** fails
7f60: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f to zero-fill sho
7f70: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 rt reads might s
7f80: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f eem to work. Ho
7f90: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 wever,.** failur
7fa0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 e to zero-fill s
7fb0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 hort reads will
7fc0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 eventually lead
7fd0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 to.** database c
7fe0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 orruption..*/.ty
7ff0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
8000: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
8010: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8020: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
8030: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a e3_io_methods {.
8040: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a int iVersion;.
8050: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 int (*xClose)(
8060: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a sqlite3_file*);.
8070: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 int (*xRead)(s
8080: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f qlite3_file*, vo
8090: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 id*, int iAmt, s
80a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
80b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 st);. int (*xWr
80c0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ite)(sqlite3_fil
80d0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c e*, const void*,
80e0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
80f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
8100: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 . int (*xTrunca
8110: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
8120: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8130: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a size);. int (*
8140: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 xSync)(sqlite3_f
8150: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 ile*, int flags)
8160: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 ;. int (*xFileS
8170: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ize)(sqlite3_fil
8180: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
8190: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 4 *pSize);. int
81a0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 (*xLock)(sqlite
81b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
81c0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 int (*xUnlock)(
81d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
81e0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 nt);. int (*xCh
81f0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 eckReservedLock)
8200: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
8210: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
8220: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 int (*xFileCont
8230: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c rol)(sqlite3_fil
8240: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 e*, int op, void
8250: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 *pArg);. int (
8260: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 *xSectorSize)(sq
8270: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
8280: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 int (*xDeviceCha
8290: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 racteristics)(sq
82a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 lite3_file*);.
82b0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
82c0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
82d0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e ersion 1 */. in
82e0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c t (*xShmMap)(sql
82f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
8300: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 iPg, int pgsz, i
8310: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c nt, void volatil
8320: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 e**);. int (*xS
8330: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f hmLock)(sqlite3_
8340: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 file*, int offse
8350: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c t, int n, int fl
8360: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ags);. void (*x
8370: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 ShmBarrier)(sqli
8380: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
8390: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 t (*xShmUnmap)(s
83a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
83b0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 t deleteFlag);.
83c0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
83d0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
83e0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f version 2 */. /
83f0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
8400: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
8410: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
8420: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
8430: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
8440: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
8450: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 l Opcodes.**.**
8460: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
8470: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f nstants are opco
8480: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c des for the xFil
8490: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
84a0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
84b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f e3_io_methods] o
84c0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 bject and for th
84d0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f e [sqlite3_file_
84e0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e control()].** in
84f0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 terface..**.** T
8500: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
8510: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f _LOCKSTATE] opco
8520: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
8530: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
8540: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
8550: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
8560: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 l method to writ
8570: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 e the current st
8580: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f ate of.** the lo
8590: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 ck (one of [SQLI
85a0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b TE_LOCK_NONE], [
85b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 SQLITE_LOCK_SHAR
85c0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ED],.** [SQLITE_
85d0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 LOCK_RESERVED],
85e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
85f0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 DING], or [SQLIT
8600: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
8610: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e ]).** into an in
8620: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 teger that the p
8630: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 Arg argument poi
8640: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 nts to. This cap
8650: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 ability.** is us
8660: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
8670: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 g and only needs
8680: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
8690: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
86a0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e T.** is defined.
86b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
86c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [[SQLITE_FCNTL_S
86d0: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 IZE_HINT]].** Th
86e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
86f0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 SIZE_HINT] opcod
8700: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c e is used by SQL
8710: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 ite to give the
8720: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 VFS.** layer a h
8730: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 int of how large
8740: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
8750: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 le will grow to
8760: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a be during the.**
8770: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 current transac
8780: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 tion. This hint
8790: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 is not guarante
87a0: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 ed to be accurat
87b0: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f e but it.** is o
87c0: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 ften close. The
87d0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 underlying VFS
87e0: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 might choose to
87f0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 preallocate data
8800: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 base.** file spa
8810: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 ce based on this
8820: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 hint in order t
8830: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f o help writes to
8840: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
8850: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 file run faster
8860: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
8870: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
8880: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b _SIZE]].** The [
8890: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 SQLITE_FCNTL_CHU
88a0: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 NK_SIZE] opcode
88b0: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 is used to reque
88c0: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a st that the VFS.
88d0: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 ** extends and t
88e0: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 runcates the dat
88f0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 abase file in ch
8900: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 unks of a size s
8910: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 pecified.** by t
8920: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 he user. The fou
8930: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
8940: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
8950: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 ntrol()] should
8960: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 .** point to an
8970: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e integer (type in
8980: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 t) containing th
8990: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 e new chunk-size
89a0: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 to use.** for t
89b0: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 he nominated dat
89c0: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e abase. Allocatin
89d0: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 g database file
89e0: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a space in large.*
89f0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d * chunks (say 1M
8a00: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 B at a time), ma
8a10: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 y reduce file-sy
8a20: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 stem fragmentati
8a30: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 on and.** improv
8a40: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e e performance on
8a50: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a some systems..*
8a60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
8a70: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 E_FCNTL_FILE_POI
8a80: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 NTER]].** The [S
8a90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
8aa0: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 _POINTER] opcode
8ab0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 is used to obta
8ac0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 in a pointer.**
8ad0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
8ae0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 file] object ass
8af0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 ociated with a p
8b00: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 articular databa
8b10: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
8b20: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 . See the [sqli
8b30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
8b40: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f ()] documentatio
8b50: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f n for.** additio
8b60: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
8b70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
8b80: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
8b90: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 MITTED]].** ^(Th
8ba0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
8bb0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 SYNC_OMITTED] op
8bc0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 code is generate
8bd0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a d internally by.
8be0: 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 ** SQLite and se
8bf0: 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 nt to all VFSes
8c00: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 in place of a ca
8c10: 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 ll to the xSync
8c20: 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 method.** when t
8c30: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
8c40: 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 ection has [PRAG
8c50: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 MA synchronous]
8c60: 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a set to OFF.)^.**
8c70: 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 Some specialize
8c80: 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 d VFSes need thi
8c90: 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 s signal in orde
8ca0: 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 r to operate cor
8cb0: 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b rectly.** when [
8cc0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
8cd0: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 us | PRAGMA sync
8ce0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 hronous=OFF] is
8cf0: 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a set, but most .*
8d00: 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e * VFSes do not n
8d10: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 eed this signal
8d20: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e and should silen
8d30: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 tly ignore this
8d40: 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 opcode..** Appli
8d50: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e cations should n
8d60: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 ot call [sqlite3
8d70: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
8d80: 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 with this.** op
8d90: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f code as doing so
8da0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 may disrupt the
8db0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 operation of th
8dc0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 e specialized VF
8dd0: 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 Ses.** that do r
8de0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
8df0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
8e00: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
8e10: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b ETRY]].** ^The [
8e20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
8e30: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 32_AV_RETRY] opc
8e40: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 ode is used to c
8e50: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 onfigure automat
8e60: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e ic.** retry coun
8e70: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 ts and intervals
8e80: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 for certain dis
8e90: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 k I/O operations
8ea0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 for the.** wind
8eb0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 ows [VFS] in ord
8ec0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f er to provide ro
8ed0: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 bustness in the
8ee0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 presence of.** a
8ef0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 nti-virus progra
8f00: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ms. By default,
8f10: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 the windows VFS
8f20: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 will retry file
8f30: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 read,.** file w
8f40: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 rite, and file d
8f50: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 elete operations
8f60: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c up to 10 times,
8f70: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a with a delay.**
8f80: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f of 25 milliseco
8f90: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 nds before the f
8fa0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 irst retry and w
8fb0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e ith the delay in
8fc0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 creasing.** by a
8fd0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 n additional 25
8fe0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 milliseconds wit
8ff0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e h each subsequen
9000: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a t retry. This.*
9010: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 * opcode allows
9020: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 these two values
9030: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 (10 retries and
9040: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
9050: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f of delay).** to
9060: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 be adjusted. T
9070: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 he values are ch
9080: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 anged for all da
9090: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
90a0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 ns.** within the
90b0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 same process.
90c0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
90d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
90e0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 array of two.**
90f0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 integers where t
9100: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 he first integer
9110: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 i the new retry
9120: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 count and the s
9130: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 econd.** integer
9140: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 is the delay.
9150: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 If either intege
9160: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 r is negative, t
9170: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a hen the setting.
9180: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 ** is not change
9190: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 d but instead th
91a0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 e prior value of
91b0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 that setting is
91c0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f written.** into
91d0: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 the array entry
91e0: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 , allowing the c
91f0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 urrent retry set
9200: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 tings to be.** i
9210: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 nterrogated. Th
9220: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 e zDbName parame
9230: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a ter is ignored..
9240: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9250: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 TE_FCNTL_PERSIST
9260: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b _WAL]].** ^The [
9270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
9280: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 SIST_WAL] opcode
9290: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 is used to set
92a0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 or query the.**
92b0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 persistent [WAL
92c0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f | Write Ahead Lo
92d0: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 g] setting. By
92e0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 default, the aux
92f0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 iliary.** write
9300: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 ahead log and sh
9310: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 ared memory file
9320: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 s used for trans
9330: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a action control.*
9340: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 * are automatica
9350: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e lly deleted when
9360: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e the latest conn
9370: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 ection to the da
9380: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 tabase.** closes
9390: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 . Setting persi
93a0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 stent WAL mode c
93b0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 auses those file
93c0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 s to persist aft
93d0: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 er.** close. Pe
93e0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c rsisting the fil
93f0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 es is useful whe
9400: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 n other processe
9410: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a s that do not.**
9420: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d have write perm
9430: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 ission on the di
9440: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 rectory containi
9450: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
9460: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 file want.** to
9470: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 read the databas
9480: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 e file, as the W
9490: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 AL and shared me
94a0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 mory files must
94b0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 exist.** in orde
94c0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 r for the databa
94d0: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c se to be readabl
94e0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 e. The fourth p
94f0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
9500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
9510: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
9520: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
9530: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
9540: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
9550: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
9560: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 to disable persi
9570: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f stent WAL mode o
9580: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 r 1 to enable pe
9590: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 rsistent.** WAL
95a0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e mode. If the in
95b0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 teger is -1, the
95c0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 n it is overwrit
95d0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 ten with the cur
95e0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 rent.** WAL pers
95f0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e istence setting.
9600: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
9610: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
9620: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a AFE_OVERWRITE]].
9630: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
9640: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f FCNTL_POWERSAFE_
9650: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 OVERWRITE] opcod
9660: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 e is used to set
9670: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a or query the.**
9680: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 persistent "pow
9690: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 ersafe-overwrite
96a0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 " or "PSOW" sett
96b0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 ing. The PSOW s
96c0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d etting.** determ
96d0: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 ines the [SQLITE
96e0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
96f0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 _OVERWRITE] bit
9700: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 of the.** xDevic
9710: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
9720: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f methods. The fo
9730: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
9740: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 o.** [sqlite3_fi
9750: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f le_control()] fo
9760: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 r this opcode sh
9770: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 ould be a pointe
9780: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e r to an integer.
9790: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 .** That integer
97a0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 is 0 to disable
97b0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 zero-damage mod
97c0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 e or 1 to enable
97d0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 zero-damage.**
97e0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e mode. If the in
97f0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 teger is -1, the
9800: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 n it is overwrit
9810: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 ten with the cur
9820: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d rent.** zero-dam
9830: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 age mode setting
9840: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
9850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
9860: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b RITE]].** ^The [
9870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 SQLITE_FCNTL_OVE
9880: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 RWRITE] opcode i
9890: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c s invoked by SQL
98a0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e ite after openin
98b0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 g.** a write tra
98c0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 nsaction to indi
98d0: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 cate that, unles
98e0: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 s it is rolled b
98f0: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 ack for some.**
9900: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 reason, the enti
9910: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 re database file
9920: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 will be overwri
9930: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 tten by the curr
9940: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 ent .** transact
9950: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 ion. This is use
9960: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 d by VACUUM oper
9970: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ations..**.** <l
9980: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
9990: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 _VFSNAME]].** ^T
99a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
99b0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 _VFSNAME] opcode
99c0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
99d0: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 obtain the names
99e0: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 of.** all [VFSe
99f0: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 s] in the VFS st
9a00: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 ack. The names
9a10: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 are of all VFS s
9a20: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 hims and the.**
9a30: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 final bottom-lev
9a40: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 el VFS are writt
9a50: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f en into memory o
9a60: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a btained from .**
9a70: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
9a80: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 ()] and the resu
9a90: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 lt is stored in
9aa0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 the char* variab
9ab0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 le.** that the f
9ac0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
9ad0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 of [sqlite3_file
9ae0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e _control()] poin
9af0: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 ts to..** The ca
9b00: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 ller is responsi
9b10: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 ble for freeing
9b20: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 the memory when
9b30: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a done. As with.*
9b40: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 * all file-contr
9b50: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 ol actions, ther
9b60: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 e is no guarante
9b70: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c e that this will
9b80: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 actually.** do
9b90: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 anything. Calle
9ba0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 rs should initia
9bb0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 lize the char* v
9bc0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c ariable to a NUL
9bd0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 L.** pointer in
9be0: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 case this file-c
9bf0: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d ontrol is not im
9c00: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 plemented. This
9c10: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a file-control.**
9c20: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 is intended for
9c30: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 diagnostic use
9c40: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e only..**.** <li>
9c50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
9c60: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e RAGMA]].** ^When
9c70: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 ever a [PRAGMA]
9c80: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 statement is par
9c90: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f sed, an [SQLITE_
9ca0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a FCNTL_PRAGMA] .*
9cb0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 * file control i
9cc0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 s sent to the op
9cd0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 en [sqlite3_file
9ce0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 ] object corresp
9cf0: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 onding.** to the
9d00: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
9d10: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 o which the prag
9d20: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 ma statement ref
9d30: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 ers. ^The argume
9d40: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 nt.** to the [SQ
9d50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
9d60: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
9d70: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a is an array of.*
9d80: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 * pointers to st
9d90: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 rings (char**) i
9da0: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f n which the seco
9db0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 nd element of th
9dc0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 e array.** is th
9dd0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 e name of the pr
9de0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 agma and the thi
9df0: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 rd element is th
9e00: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 e argument to th
9e10: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e e.** pragma or N
9e20: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d ULL if the pragm
9e30: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e a has no argumen
9e40: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 t. ^The handler
9e50: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 for an.** [SQLI
9e60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
9e70: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 file control ca
9e80: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b n optionally mak
9e90: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d e the first elem
9ea0: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 ent.** of the ch
9eb0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f ar** argument po
9ec0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 int to a string
9ed0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
9ee0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 qlite3_mprintf()
9ef0: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 ].** or the equi
9f00: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 valent and that
9f10: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f string will beco
9f20: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 me the result of
9f30: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a the pragma or.*
9f40: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 * the error mess
9f50: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d age if the pragm
9f60: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 a fails. ^If the
9f70: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
9f80: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
9f90: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b ontrol returns [
9fa0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
9fb0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a , then normal .*
9fc0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 * [PRAGMA] proce
9fd0: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e ssing continues.
9fe0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 ^If the [SQLIT
9ff0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a E_FCNTL_PRAGMA].
a000: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 ** file control
a010: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
a020: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 OK], then the pa
a030: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 rser assumes tha
a040: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 t the.** VFS has
a050: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 handled the PRA
a060: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 GMA itself and t
a070: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 he parser genera
a080: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 tes a no-op.** p
a090: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
a0a0: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c t. ^If the [SQL
a0b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a0c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 ] file control r
a0d0: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 eturns.** any re
a0e0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 sult code other
a0f0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d than [SQLITE_OK]
a100: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 or [SQLITE_NOTF
a110: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e OUND], that mean
a120: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 s.** that the VF
a130: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e S encountered an
a140: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e error while han
a150: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d dling the [PRAGM
a160: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f A] and the.** co
a170: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 mpilation of the
a180: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 PRAGMA fails wi
a190: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 th an error. ^T
a1a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
a1b0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 _PRAGMA].** file
a1c0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 control occurs
a1d0: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 at the beginning
a1e0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 of pragma state
a1f0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e ment analysis an
a200: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 d so.** it is ab
a210: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 le to override b
a220: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d uilt-in [PRAGMA]
a230: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a statements..**.
a240: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
a250: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 FCNTL_BUSYHANDLE
a260: 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c R]].** ^This fil
a270: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 e-control may be
a280: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 invoked by SQLi
a290: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 te on the databa
a2a0: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a se file handle.*
a2b0: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 * shortly after
a2c0: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 it is opened in
a2d0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 order to provide
a2e0: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 a custom VFS wi
a2f0: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 th access.** to
a300: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 the connections
a310: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c busy-handler cal
a320: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d lback. The argum
a330: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 ent is of type (
a340: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e void **).** - an
a350: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 array of two (v
a360: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 oid *) values. T
a370: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a he first (void *
a380: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 ) actually point
a390: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 s.** to a functi
a3a0: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 on of type (int
a3b0: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e (*)(void *)). In
a3c0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 order to invoke
a3d0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 the connections
a3e0: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 .** busy-handler
a3f0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 , this function
a400: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 should be invoke
a410: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e d with the secon
a420: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a d (void *) in.**
a430: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 the array as th
a440: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e e only argument.
a450: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e If it returns n
a460: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 on-zero, then th
a470: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 e operation.** s
a480: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 hould be retried
a490: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 . If it returns
a4a0: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d zero, the custom
a4b0: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e VFS should aban
a4c0: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 don the.** curre
a4d0: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a nt operation..**
a4e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
a4f0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
a500: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 AME]].** ^Applic
a510: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 ation can invoke
a520: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 this file-contr
a530: 6f 6c 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 ol to have SQLit
a540: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 e generate a.**
a550: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 temporary filena
a560: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d me using the sam
a570: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 e algorithm that
a580: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 is followed to
a590: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 generate.** temp
a5a0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 orary filenames
a5b0: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 for TEMP tables
a5c0: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e and other intern
a5d0: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a al uses. The.**
a5e0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 argument should
a5f0: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 be a char** whi
a600: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 ch will be fille
a610: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e d with the filen
a620: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 ame.** written i
a630: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
a640: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
a650: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 3_malloc()]. Th
a660: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a e caller should.
a670: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ** invoke [sqlit
a680: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 e3_free()] on th
a690: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 e result to avoi
a6a0: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e d a memory leak.
a6b0: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a .**.** </ul>.*/.
a6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
a6d0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 CNTL_LOCKSTATE
a6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 1.#
a6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 define SQLITE_GE
a700: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
a710: 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 2.#d
a720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 efine SQLITE_SET
a730: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
a740: 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 3.#de
a750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 fine SQLITE_LAST
a760: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 _ERRNO
a770: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 4.#def
a780: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
a790: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 _SIZE_HINT
a7a0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
a7b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
a7c0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 CHUNK_SIZE
a7d0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 e SQLITE_FCNTL_F
a7f0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 ILE_POINTER
a800: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 7.#define
a810: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
a820: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 NC_OMITTED
a830: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 8.#define
a840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
a850: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 32_AV_RETRY
a860: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 9.#define S
a870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 QLITE_FCNTL_PERS
a880: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 IST_WAL
a890: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 10.#define SQ
a8a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 LITE_FCNTL_OVERW
a8b0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 RITE
a8c0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 11.#define SQL
a8d0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d ITE_FCNTL_VFSNAM
a8e0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
a8f0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 12.#define SQLI
a900: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 TE_FCNTL_POWERSA
a910: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 FE_OVERWRITE
a920: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 13.#define SQLIT
a930: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 E_FCNTL_PRAGMA
a940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
a950: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
a960: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
a970: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 ER 15
a980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
a990: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
a9a0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a ME 16.
a9b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
a9c0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
a9d0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
a9e0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
a9f0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
aa00: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
aa10: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
aa20: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
aa30: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
aa40: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
aa50: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
aa60: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
aa70: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
aa80: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
aa90: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
aaa0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
aab0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
aac0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
aad0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
aae0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
aaf0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
ab00: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
ab10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
ab20: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
ab30: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
ab40: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
ab50: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
ab60: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
ab70: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
ab80: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
ab90: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
aba0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
abb0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
abc0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
abd0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
abe0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
abf0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
ac00: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
ac10: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
ac20: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
ac30: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
ac40: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
ac50: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
ac60: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
ac70: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
ac80: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
ac90: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
aca0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
acb0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
acc0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
acd0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
ace0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
acf0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
ad00: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
ad10: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
ad20: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
ad30: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
ad40: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
ad50: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
ad60: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
ad70: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
ad80: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
ad90: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
ada0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
adb0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
adc0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
add0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
ade0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
adf0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
ae00: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
ae10: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
ae20: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
ae30: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
ae40: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
ae50: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
ae60: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
ae70: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
ae80: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
ae90: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
aea0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
aeb0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
aec0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
aed0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
aee0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
aef0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
af00: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
af10: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
af20: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
af30: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
af40: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
af50: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
af60: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
af70: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
af80: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
af90: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
afa0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
afb0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
afc0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
afd0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
afe0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
aff0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
b000: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
b010: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
b020: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
b030: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
b040: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
b050: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
b060: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
b070: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
b080: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
b090: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
b0a0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
b0b0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
b0c0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
b0d0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
b0e0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
b0f0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
b100: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
b110: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
b120: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
b130: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
b140: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
b150: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
b160: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
b170: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
b180: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
b190: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
b1a0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
b1b0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
b1c0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
b1d0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
b1e0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
b1f0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
b200: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
b210: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
b220: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
b230: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
b240: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
b250: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
b260: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
b270: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
b280: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
b290: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
b2a0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
b2b0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
b2c0: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
b2d0: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
b2e0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
b2f0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
b300: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
b310: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
b320: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
b330: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
b340: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
b350: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
b360: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
b370: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
b380: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
b390: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
b3a0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
b3b0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
b3c0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
b3d0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
b3e0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
b3f0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
b400: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
b410: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
b420: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
b430: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
b440: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
b450: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
b460: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
b470: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
b480: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
b490: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
b4a0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
b4b0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
b4c0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
b4d0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
b4e0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
b4f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
b500: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
b510: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
b520: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
b530: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
b540: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
b550: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
b560: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
b570: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
b580: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
b590: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
b5a0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
b5b0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
b5c0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
b5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
b5e0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
b5f0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
b600: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
b610: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
b620: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
b630: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
b640: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
b650: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
b660: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
b670: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
b680: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
b690: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
b6a0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
b6b0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
b6c0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
b6d0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
b6e0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
b6f0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
b700: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
b710: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
b720: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
b730: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
b740: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
b750: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
b760: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
b770: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
b780: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
b790: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
b7a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
b7b0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
b7c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
b7d0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
b7e0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
b7f0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
b800: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
b810: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
b820: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
b830: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
b840: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
b850: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
b860: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
b870: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
b880: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
b890: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
b8a0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
b8b0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
b8c0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
b8d0: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
b8e0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
b8f0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
b900: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
b910: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
b920: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
b930: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
b940: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
b950: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
b960: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
b970: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
b980: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
b990: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
b9a0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
b9b0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
b9c0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
b9d0: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
b9e0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
b9f0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
ba00: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
ba10: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
ba20: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
ba30: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
ba40: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
ba50: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
ba60: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
ba70: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
ba80: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
ba90: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
baa0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
bab0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
bac0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
bad0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
bae0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
baf0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
bb00: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
bb10: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
bb20: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
bb30: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
bb40: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
bb50: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
bb60: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
bb70: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
bb80: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
bb90: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
bba0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
bbb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
bbc0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
bbd0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
bbe0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
bbf0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
bc00: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
bc10: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
bc20: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
bc30: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
bc40: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
bc50: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
bc60: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
bc70: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
bc80: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
bc90: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
bca0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
bcb0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
bcc0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
bcd0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
bce0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
bcf0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
bd00: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
bd10: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
bd20: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
bd30: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
bd40: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
bd50: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
bd60: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
bd70: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
bd80: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
bd90: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
bda0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
bdb0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
bdc0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
bdd0: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
bde0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
bdf0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
be00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
be10: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
be20: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
be30: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
be40: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
be50: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
be60: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
be70: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
be80: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
be90: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
bea0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
beb0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
bec0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
bed0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
bee0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
bef0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
bf00: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
bf10: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
bf20: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
bf30: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
bf40: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
bf50: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
bf60: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
bf70: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
bf80: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
bf90: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
bfa0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
bfb0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
bfc0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
bfd0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
bfe0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
bff0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
c000: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
c010: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
c020: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
c030: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
c040: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
c050: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
c060: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
c070: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
c080: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
c090: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
c0a0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
c0b0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
c0c0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
c0d0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
c0e0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
c0f0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
c100: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
c110: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
c120: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
c130: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
c140: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
c150: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
c160: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
c170: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
c180: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
c190: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
c1a0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
c1b0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
c1c0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
c1d0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
c1e0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
c1f0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
c200: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
c210: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
c220: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
c230: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
c240: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
c250: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
c260: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
c270: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
c280: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
c290: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
c2a0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
c2b0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
c2c0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
c2d0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
c2e0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
c2f0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
c300: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
c310: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
c320: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
c330: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
c340: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
c350: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
c360: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
c370: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
c380: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
c390: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
c3a0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
c3b0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
c3c0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
c3d0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
c3e0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
c3f0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
c400: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
c410: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
c420: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
c430: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
c440: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
c450: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
c460: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
c470: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
c480: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
c490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
c4a0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
c4b0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
c4c0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
c4d0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
c4e0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
c4f0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
c500: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
c510: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
c520: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
c530: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
c540: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
c550: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
c560: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
c570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
c580: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
c590: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
c5a0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
c5b0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
c5c0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
c5d0: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
c5e0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
c5f0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
c600: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
c610: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
c620: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
c630: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
c640: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
c650: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
c660: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
c670: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
c680: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
c690: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
c6a0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
c6b0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
c6c0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
c6d0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
c6e0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
c6f0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
c700: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
c710: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
c720: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
c730: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
c740: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
c750: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
c760: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
c770: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
c780: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
c790: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
c7a0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
c7b0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
c7c0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
c7d0: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
c7e0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
c7f0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
c800: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
c810: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
c820: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
c830: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
c840: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
c850: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
c860: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
c870: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
c880: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
c890: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
c8a0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
c8b0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
c8c0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
c8d0: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
c8e0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
c8f0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
c900: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
c910: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
c920: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
c930: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
c940: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
c950: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
c960: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
c970: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
c980: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
c990: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
c9a0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
c9b0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
c9c0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
c9d0: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
c9e0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
c9f0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
ca00: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
ca10: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
ca20: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
ca30: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
ca40: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
ca50: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
ca60: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
ca70: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
ca80: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
ca90: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
caa0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
cab0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
cac0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
cad0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
cae0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
caf0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
cb00: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
cb10: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
cb20: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
cb30: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
cb40: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
cb50: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
cb60: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
cb70: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
cb80: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
cb90: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
cba0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
cbb0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
cbc0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
cbd0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
cbe0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
cbf0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
cc00: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
cc10: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
cc20: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
cc30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
cc40: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
cc50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
cc60: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
cc70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
cc80: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
cc90: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
cca0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
ccb0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
ccc0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
ccd0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
cce0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
ccf0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
cd00: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
cd10: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
cd20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
cd30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
cd40: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
cd50: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
cd60: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
cd70: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
cd80: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
cd90: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
cda0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
cdb0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
cdc0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
cdd0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
cde0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
cdf0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
ce00: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
ce10: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
ce20: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
ce30: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
ce40: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
ce50: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
ce60: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
ce70: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
ce80: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
ce90: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
cea0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
ceb0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
cec0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
ced0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
cee0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
cef0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
cf00: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
cf10: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
cf20: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
cf30: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
cf40: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
cf50: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
cf60: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
cf70: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
cf80: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
cf90: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
cfa0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
cfb0: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
cfc0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
cfd0: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
cfe0: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
cff0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
d000: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
d010: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
d020: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
d030: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
d040: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
d050: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
d060: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
d070: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
d080: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
d090: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
d0a0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
d0b0: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
d0c0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
d0d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
d0e0: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
d0f0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
d100: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
d110: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
d120: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
d130: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
d140: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
d150: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 pended in figure
d160: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
d170: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
d180: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
d190: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
d1a0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
d1b0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
d1c0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
d1d0: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
d1e0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
d1f0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
d200: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
d210: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
d220: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
d230: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
d240: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
d250: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
d260: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
d270: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
d280: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
d290: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
d2a0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
d2b0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
d2c0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
d2d0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
d2e0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
d2f0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
d300: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
d310: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
d320: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
d330: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
d340: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
d350: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
d360: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
d370: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
d380: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
d390: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
d3a0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
d3b0: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
d3c0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
d3d0: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
d3e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
d3f0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
d400: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
d410: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
d420: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
d430: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
d440: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
d450: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
d460: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
d470: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
d480: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
d490: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
d4a0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
d4b0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
d4c0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
d4d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
d4e0: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
d4f0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
d500: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
d510: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
d520: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
d530: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
d540: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
d550: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
d560: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
d570: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
d580: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
d590: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
d5a0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
d5b0: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
d5c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
d5d0: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
d5e0: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
d5f0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
d600: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
d610: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
d620: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
d630: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
d640: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
d650: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
d660: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
d670: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
d680: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
d690: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
d6a0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
d6b0: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
d6c0: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
d6d0: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
d6e0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
d6f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
d700: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
d710: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
d720: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
d730: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
d740: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
d750: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
d760: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
d770: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
d780: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
d790: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
d7a0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
d7b0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
d7c0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
d7d0: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
d7e0: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
d7f0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
d800: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
d810: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 was given no th
d820: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
d830: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
d840: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
d850: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
d860: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
d870: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
d880: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
d890: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
d8a0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
d8b0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
d8c0: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
d8d0: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
d8e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
d8f0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
d900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
d910: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
d920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d930: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
d940: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
d950: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
d960: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
d970: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
d980: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
d990: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
d9a0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
d9b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
d9c0: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
d9d0: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
d9e0: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
d9f0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
da00: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
da10: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
da20: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
da30: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
da40: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
da50: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
da60: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
da70: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
da80: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
da90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
daa0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
dab0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
dac0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
dad0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
dae0: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
daf0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
db00: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
db10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
db20: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
db30: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
db40: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
db50: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
db60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
db70: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
db80: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
db90: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
dba0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
dbb0: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
dbc0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
dbd0: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
dbe0: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
dbf0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
dc00: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
dc10: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
dc20: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
dc30: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
dc40: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
dc50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
dc60: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
dc70: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
dc80: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
dc90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
dca0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
dcb0: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
dcc0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
dcd0: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
dce0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
dcf0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
dd00: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
dd10: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
dd20: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
dd30: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
dd40: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
dd50: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
dd60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
dd70: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
dd80: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
dd90: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
dda0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
ddb0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
ddc0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
ddd0: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
dde0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
ddf0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
de00: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
de10: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
de20: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
de30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
de40: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
de50: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
de60: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
de70: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
de80: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
de90: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
dea0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
deb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
dec0: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
ded0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
dee0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
def0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
df00: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
df10: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
df20: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
df30: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
df40: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
df50: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
df60: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
df70: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
df80: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
df90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
dfa0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
dfb0: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
dfc0: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
dfd0: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
dfe0: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
dff0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
e000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
e010: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
e020: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
e030: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e040: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
e050: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
e060: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
e070: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
e080: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
e090: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
e0a0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
e0b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
e0c0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
e0d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
e0e0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
e0f0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
e100: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
e110: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
e120: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
e130: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
e140: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
e150: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
e160: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
e170: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
e180: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
e190: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
e1a0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
e1b0: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
e1c0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
e1d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
e1e0: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
e1f0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
e200: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
e210: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
e220: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
e230: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
e240: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
e250: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
e260: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
e270: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
e280: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
e290: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
e2a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e2b0: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
e2c0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
e2d0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
e2e0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
e2f0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
e300: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
e310: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
e320: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
e330: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
e340: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
e350: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
e360: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
e370: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
e380: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
e390: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
e3a0: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
e3b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
e3c0: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
e3d0: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
e3e0: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
e3f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
e400: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
e410: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
e420: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
e430: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
e440: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
e450: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
e460: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
e470: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
e480: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
e490: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
e4a0: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
e4b0: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
e4c0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
e4d0: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
e4e0: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
e4f0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
e500: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
e510: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
e520: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
e530: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
e540: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
e550: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
e560: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
e570: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
e580: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
e590: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
e5a0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
e5b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
e5c0: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
e5d0: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
e5e0: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
e5f0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
e600: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
e610: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
e620: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
e630: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
e640: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
e650: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
e660: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
e670: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
e680: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
e690: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
e6a0: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
e6b0: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
e6c0: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
e6d0: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
e6e0: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
e6f0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
e700: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
e710: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
e720: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
e730: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
e740: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
e750: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
e760: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
e770: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
e780: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
e790: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
e7a0: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
e7b0: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
e7c0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
e7d0: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
e7e0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
e7f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
e800: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
e810: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
e820: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
e830: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
e840: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
e850: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
e860: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
e870: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
e880: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
e890: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
e8a0: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
e8b0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
e8c0: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
e8d0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
e8e0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
e8f0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
e900: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
e910: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
e920: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
e930: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
e940: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
e950: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
e960: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
e970: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
e980: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
e990: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
e9a0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
e9b0: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
e9c0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
e9d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
e9e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
e9f0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
ea00: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
ea10: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
ea20: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
ea30: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
ea40: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
ea50: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
ea60: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
ea70: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
ea80: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
ea90: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
eaa0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
eab0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
eac0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
ead0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 lize(void);.SQLI
eae0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
eaf0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 e3_shutdown(void
eb00: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
eb10: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
eb20: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f t(void);.SQLITE_
eb30: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
eb40: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
eb50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
eb60: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
eb70: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
eb80: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
eb90: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
eba0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
ebb0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
ebc0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
ebd0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
ebe0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
ebf0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
ec00: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
ec10: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
ec20: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
ec30: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
ec40: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
ec50: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
ec60: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
ec70: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
ec80: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
ec90: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
eca0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
ecb0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
ecc0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
ecd0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 needs..**.** The
ece0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
ecf0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e ) interface is n
ed00: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 ot threadsafe.
ed10: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a The application.
ed20: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 ** must insure t
ed30: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c hat no other SQL
ed40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
ed50: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 re invoked by ot
ed60: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 her.** threads w
ed70: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e hile sqlite3_con
ed80: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 fig() is running
ed90: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 . Furthermore,
eda0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
edb0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 .** may only be
edc0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f invoked prior to
edd0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c library initial
ede0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a ization using.**
edf0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
ee00: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
ee10: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 shutdown by [sq
ee20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
ee30: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
ee40: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 3_config() is ca
ee50: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
ee60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
ee70: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 ] and before.**
ee80: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
ee90: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c n()] then it wil
eea0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f l return SQLITE_
eeb0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c MISUSE..** Note,
eec0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e however, that ^
eed0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
eee0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 can be called a
eef0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a s part of the.**
ef00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
ef10: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f of an applicatio
ef20: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 n-defined [sqlit
ef30: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a e3_os_init()]..*
ef40: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
ef50: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
ef60: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 e3_config() is a
ef70: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f n integer.** [co
ef80: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
ef90: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 on] that determi
efa0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 nes.** what prop
efb0: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 erty of SQLite i
efc0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 s to be configur
efd0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 ed. Subsequent
efe0: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 arguments.** var
eff0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 y depending on t
f000: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f he [configuratio
f010: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 n option].** in
f020: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
f030: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 nt..**.** ^When
f040: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 a configuration
f050: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 option is set, s
f060: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
f070: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
f080: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 OK]..** ^If the
f090: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 option is unknow
f0a0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 n or SQLite is u
f0b0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 nable to set the
f0c0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 option.** then
f0d0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 this routine ret
f0e0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 urns a non-zero
f0f0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f [error code]..*/
f100: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
f110: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 sqlite3_config(i
f120: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a nt, ...);../*.**
f130: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 CAPI3REF: Confi
f140: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f gure database co
f150: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 nnections.**.**
f160: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 The sqlite3_db_c
f170: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 onfig() interfac
f180: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b e is used to mak
f190: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a e configuration.
f1a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 ** changes to a
f1b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
f1c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 tion]. The inte
f1d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 rface is similar
f1e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
f1f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 config()] except
f200: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 that the change
f210: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e s apply to a sin
f220: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 gle.** [database
f230: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 connection] (sp
f240: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 ecified in the f
f250: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a irst argument)..
f260: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 **.** The second
f270: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
f280: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 ite3_db_config(D
f290: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a ,V,...) is the.
f2a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e ** [SQLITE_DBCON
f2b0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 FIG_LOOKASIDE |
f2c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
f2d0: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 rb] - an integer
f2e0: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 code .** that i
f2f0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 ndicates what as
f300: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 pect of the [dat
f310: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
f320: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 ] is being confi
f330: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 gured..** Subseq
f340: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 uent arguments v
f350: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
f360: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
f370: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e on verb..**.** ^
f380: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
f390: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 _db_config() ret
f3a0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 urn SQLITE_OK if
f3b0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 and only if.**
f3c0: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 the call is cons
f3d0: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 idered successfu
f3e0: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 l..*/.SQLITE_API
f3f0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f int sqlite3_db_
f400: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c config(sqlite3*,
f410: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a int op, ...);..
f420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
f430: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f Memory Allocatio
f440: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a n Routines.**.**
f450: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
f460: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 this object defi
f470: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 nes the interfac
f480: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 e between SQLite
f490: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 .** and low-leve
f4a0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
f4b0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ion routines..**
f4c0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 .** This object
f4d0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 is used in only
f4e0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 one place in the
f4f0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
f500: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 e..** A pointer
f510: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
f520: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 f this object is
f530: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f the argument to
f540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
f550: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 fig()] when the
f560: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
f570: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 tion is.** [SQLI
f580: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
f590: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e ] or [SQLITE_CON
f5a0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 FIG_GETMALLOC].
f5b0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 .** By creating
f5c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
f5d0: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 this object.** a
f5e0: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f nd passing it to
f5f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
f600: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ]([SQLITE_CONFIG
f610: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 _MALLOC]).** dur
f620: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
f630: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f n, an applicatio
f640: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e n can specify an
f650: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
f660: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
f670: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 n subsystem for
f680: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f SQLite to use fo
f690: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 r all of its.**
f6a0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e dynamic memory n
f6b0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 eeds..**.** Note
f6c0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d that SQLite com
f6d0: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 es with several
f6e0: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 [built-in memory
f6f0: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 allocators].**
f700: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 that are perfect
f710: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 ly adequate for
f720: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 the overwhelming
f730: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 majority of app
f740: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 lications.** and
f750: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 that this objec
f760: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c t is only useful
f770: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 to a tiny minor
f780: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
f790: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 ons.** with spec
f7a0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 ialized memory a
f7b0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 llocation requir
f7c0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 ements. This ob
f7d0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 ject is.** also
f7e0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 used during test
f7f0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e ing of SQLite in
f800: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 order to specif
f810: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 y an alternative
f820: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
f830: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 ator that simula
f840: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f tes memory out-o
f850: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 f-memory conditi
f860: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 ons in.** order
f870: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 to verify that S
f880: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 QLite recovers g
f890: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 racefully from s
f8a0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e uch.** condition
f8b0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 s..**.** The xMa
f8c0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 lloc, xRealloc,
f8d0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 and xFree method
f8e0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 s must work like
f8f0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 the.** malloc()
f900: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 , realloc() and
f910: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 free() functions
f920: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 from the standa
f930: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a rd C library..**
f940: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
f950: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 ees that the sec
f960: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
f970: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 ** xRealloc is a
f980: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 lways a value re
f990: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f turned by a prio
f9a0: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 r call to xRound
f9b0: 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 up..**.** xSize
f9c0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 should return th
f9d0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 e allocated size
f9e0: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c of a memory all
f9f0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 ocation.** previ
fa00: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 ously obtained f
fa10: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 rom xMalloc or x
fa20: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c Realloc. The al
fa30: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 located size.**
fa40: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 is always at lea
fa50: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 st as big as the
fa60: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 requested size
fa70: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 but may be large
fa80: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f r..**.** The xRo
fa90: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 undup method ret
faa0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 urns what would
fab0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 be the allocated
fac0: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 size of.** a me
fad0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
fae0: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c given a particul
faf0: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a ar requested siz
fb00: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a e. Most memory.
fb10: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f ** allocators ro
fb20: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c und up memory al
fb30: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 locations at lea
fb40: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d st to the next m
fb50: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e ultiple.** of 8.
fb60: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 Some allocator
fb70: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 s round up to a
fb80: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 larger multiple
fb90: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 or to a power of
fba0: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 2..** Every mem
fbb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
fbc0: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e equest coming in
fbd0: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 through [sqlite
fbe0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 3_malloc()].** o
fbf0: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c r [sqlite3_reall
fc00: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c oc()] first call
fc10: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 s xRoundup. If
fc20: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 xRoundup returns
fc30: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 0, .** that cau
fc40: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f ses the correspo
fc50: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c nding memory all
fc60: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e ocation to fail.
fc70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 .**.** The xInit
fc80: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 method initiali
fc90: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 zes the memory a
fca0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 llocator. (For
fcb0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d example,.** it m
fcc0: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e ight allocate an
fcd0: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 y require mutexe
fce0: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 s or initialize
fcf0: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a internal data.**
fd00: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 structures. Th
fd10: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 e xShutdown meth
fd20: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 od is invoked (i
fd30: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a ndirectly) by.**
fd40: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
fd50: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 wn()] and should
fd60: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 deallocate any
fd70: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 resources acquir
fd80: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 ed.** by xInit.
fd90: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f The pAppData po
fda0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 inter is used as
fdb0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
fdc0: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 ter to.** xInit
fdd0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a and xShutdown..*
fde0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 *.** SQLite hold
fdf0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
fe00: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 TEX_STATIC_MASTE
fe10: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 R] mutex when it
fe20: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 invokes.** the
fe30: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f xInit method, so
fe40: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
fe50: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 d need not be th
fe60: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a readsafe. The.*
fe70: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 * xShutdown meth
fe80: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 od is only calle
fe90: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
fea0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 shutdown()] so i
feb0: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 t does.** not ne
fec0: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 ed to be threads
fed0: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 afe either. For
fee0: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f all other metho
fef0: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f ds, SQLite.** ho
ff00: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f lds the [SQLITE_
ff10: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d MUTEX_STATIC_MEM
ff20: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 ] mutex as long
ff30: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 as the.** [SQLIT
ff40: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
ff50: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f US] configuratio
ff60: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e n option is turn
ff70: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 ed on (which.**
ff80: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 it is by default
ff90: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 ) and so the met
ffa0: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 hods are automat
ffb0: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 ically serialize
ffc0: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 d..** However, i
ffd0: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
ffe0: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 _MEMSTATUS] is d
fff0: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 isabled, then th
10000 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f e other.** metho
10010 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 ds must be threa
10020 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 dsafe or else ma
10030 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 ke their own arr
10040 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a angements for.**
10050 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a serialization..
10060 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c **.** SQLite wil
10070 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 l never invoke x
10080 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e Init() more than
10090 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e once without an
100a0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 intervening.**
100b0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 call to xShutdow
100c0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 n()..*/.typedef
100d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
100e0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 em_methods sqlit
100f0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a e3_mem_methods;.
10100 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
10110 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 em_methods {. v
10120 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 oid *(*xMalloc)(
10130 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a int); /*
10140 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 Memory allocati
10150 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 on function */.
10160 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 void (*xFree)(v
10170 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
10180 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 /* Free a prior
10190 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
101a0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 void *(*xRealloc
101b0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f )(void*,int); /
101c0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f * Resize an allo
101d0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
101e0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b (*xSize)(void*);
101f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 /* Re
10200 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 turn the size of
10210 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
10220 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 /. int (*xRound
10230 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 up)(int);
10240 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 /* Round up r
10250 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 equest size to a
10260 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a llocation size *
10270 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 /. int (*xInit)
10280 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
10290 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 /* Initialize
102a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
102b0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
102c0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 (*xShutdown)(voi
102d0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 d*); /* Dei
102e0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
102f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
10300 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
10310 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 ta;
10320 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 /* Argument t
10330 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 o xInit() and xS
10340 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a hutdown() */.};.
10350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
10360 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
10370 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 ptions.** KEYWOR
10380 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 DS: {configurati
10390 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a on option}.**.**
103a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
103b0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
103c0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
103d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
103e0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
103f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 passed as the fi
10400 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
10410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e the [sqlite3_con
10420 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
10430 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
10440 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
10450 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
10460 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
10470 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
10480 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
10490 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
104a0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
104b0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
104c0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
104d0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
104e0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
104f0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 3_config()] to m
10500 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a ake sure that.**
10510 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 the call worked
10520 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
10530 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
10540 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
10550 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
10560 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
10570 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
10580 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
10590 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
105a0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
105b0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
105c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
105d0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 NGLETHREAD]] <dt
105e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 >SQLITE_CONFIG_S
105f0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e INGLETHREAD</dt>
10600 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
10610 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
10620 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
10630 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
10640 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
10650 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e ing mode] to Sin
10660 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 gle-thread. In
10670 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
10680 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 disables.** all
10690 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 mutexing and put
106a0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 s SQLite into a
106b0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 mode where it ca
106c0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a n only be used.*
106d0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 * by a single th
106e0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 read. ^If SQLi
106f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
10700 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
10710 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
10720 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
10730 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
10740 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
10750 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
10760 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 ble to change th
10770 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
10780 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 e] from its defa
10790 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 ult.** value of
107a0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e Single-thread an
107b0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f d so [sqlite3_co
107c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
107d0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f urn .** [SQLITE_
107e0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
107f0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
10800 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
10810 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 READ.** configur
10820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
10830 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
10840 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
10850 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 READ]] <dt>SQLIT
10860 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
10870 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
10880 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
10890 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
108a0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
108b0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
108c0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
108d0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 e] to Multi-thre
108e0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
108f0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
10900 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 .** mutexing on
10910 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10920 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 tion] and [prepa
10930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
10940 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 bjects..** The a
10950 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 pplication is re
10960 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 sponsible for se
10970 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 rializing access
10980 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 to.** [database
10990 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e connections] an
109a0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
109b0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 ements]. But ot
109c0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 her mutexes.** a
109d0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 re enabled so th
109e0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 at SQLite will b
109f0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e e safe to use in
10a00 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
10a10 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 d.** environment
10a20 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 as long as no t
10a30 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d wo threads attem
10a40 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 pt to use the sa
10a50 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 me.** [database
10a60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 connection] at t
10a70 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e he same time. ^
10a80 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
10a90 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
10aa0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
10ab0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
10ac0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
10ad0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
10ae0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
10af0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 t possible to se
10b00 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 t the Multi-thre
10b10 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
10b20 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
10b30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
10b40 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
10b50 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
10b60 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
10b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
10b80 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 TITHREAD configu
10b90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
10ba0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
10bb0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c TE_CONFIG_SERIAL
10bc0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 IZED]] <dt>SQLIT
10bd0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
10be0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ZED</dt>.** <dd>
10bf0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
10c00 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
10c10 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
10c20 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
10c30 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
10c40 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e ] to Serialized.
10c50 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
10c60 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 this option ena
10c70 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 bles.** all mute
10c80 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 xes including th
10c90 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d e recursive.** m
10ca0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 utexes on [datab
10cb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
10cc0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
10cd0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 atement] objects
10ce0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 ..** In this mod
10cf0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 e (which is the
10d00 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c default when SQL
10d10 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
10d20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f with.** [SQLITE_
10d30 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 THREADSAFE=1]) t
10d40 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
10d50 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 y will itself se
10d60 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a rialize access.*
10d70 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 * to [database c
10d80 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
10d90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
10da0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 ents] so that th
10db0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e e.** application
10dc0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 is free to use
10dd0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
10de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
10df0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 r the.** same [p
10e00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
10e10 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 t] in different
10e20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 threads at the s
10e30 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 ame time..** ^If
10e40 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
10e50 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
10e60 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
10e70 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
10e80 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
10e90 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
10ea0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
10eb0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
10ec0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b the Serialized [
10ed0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
10ee0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
10ef0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 config()] will r
10f00 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 eturn [SQLITE_ER
10f10 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
10f20 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 ith the.** SQLIT
10f30 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 E_CONFIG_SERIALI
10f40 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ZED configuratio
10f50 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
10f60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
10f70 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 NFIG_MALLOC]] <d
10f80 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
10f90 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c MALLOC</dt>.** <
10fa0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f dd> ^(This optio
10fb0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
10fc0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
10fd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
10fe0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f an.** instance o
10ff0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
11000 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
11010 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 cture. The argu
11020 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
11030 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
11040 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
11050 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
11060 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
11070 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
11080 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11090 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
110a0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
110b0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
110c0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
110d0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
110e0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
110f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
11100 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
11110 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
11120 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
11130 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
11140 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
11150 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
11160 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
11170 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f NFIG_GETMALLOC</
11180 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
11190 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 is option takes
111a0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
111b0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 t which is a poi
111c0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e nter to an.** in
111d0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
111e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
111f0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 ds] structure.
11200 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d The [sqlite3_mem
11210 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
11220 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
11230 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
11240 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f tly defined memo
11250 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
11260 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
11270 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
11280 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
11290 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d the default mem
112a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
112b0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 * routines with
112c0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 a wrapper that s
112d0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 imulations memor
112e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
112f0 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b lure or.** track
11300 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 s memory usage,
11310 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 for example. </d
11320 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
11330 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
11340 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f US]] <dt>SQLITE_
11350 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
11360 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
11370 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
11380 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
11390 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e of type int, in
113a0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a terpreted as a .
113b0 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 ** boolean, whic
113c0 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 h enables or dis
113d0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 ables the collec
113e0 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 tion of memory a
113f0 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 llocation .** st
11400 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
11410 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11420 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
11430 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 e disabled, the
11440 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 .** following SQ
11450 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 Lite interfaces
11460 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 become non-opera
11470 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c tional:.** <ul
11480 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c >.** <li> [sql
11490 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
114a0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
114b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 qlite3_memory_hi
114c0 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 ghwater()].**
114d0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f <li> [sqlite3_so
114e0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 ft_heap_limit64(
114f0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
11500 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a lite3_status()].
11510 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 ** </ul>)^.**
11520 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 ^Memory allocati
11530 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
11540 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
11550 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 ault unless SQLi
11560 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
11570 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 d with [SQLITE_D
11580 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 EFAULT_MEMSTATUS
11590 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 ]=0 in which cas
115a0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
115b0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
115c0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 s are disabled b
115d0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f y default..** </
115e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
115f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
11600 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 H]] <dt>SQLITE_C
11610 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 ONFIG_SCRATCH</d
11620 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
11630 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
11640 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
11650 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 y buffer that SQ
11660 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
11670 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f .** scratch memo
11680 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 ry. There are t
11690 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
116a0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
116b0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
116c0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
116d0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
116e0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
116f0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 will be.** draw
11700 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 n, the size of e
11710 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f ach scratch allo
11720 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 cation (sz),.**
11730 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 and the maximum
11740 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 number of scratc
11750 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e h allocations (N
11760 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 ). The sz.** ar
11770 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
11780 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e multiple of 16.
11790 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
117a0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 gument must be a
117b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 pointer to an 8
117c0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 -byte aligned bu
117d0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 ffer.** of at le
117e0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f ast sz*N bytes o
117f0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 f memory..** ^SQ
11800 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f Lite will use no
11810 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 more than two s
11820 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 cratch buffers p
11830 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a er thread. So.*
11840 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 * N should be se
11850 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 t to twice the e
11860 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 xpected maximum
11870 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 number of thread
11880 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 s..** ^SQLite wi
11890 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 ll never require
118a0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 a scratch buffe
118b0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 r that is more t
118c0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 han 6.** times t
118d0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 he database page
118e0 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 size. ^If SQLit
118f0 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 e needs needs ad
11900 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 ditional.** scra
11910 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e tch memory beyon
11920 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
11930 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 ed by this confi
11940 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c guration option,
11950 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 then .** [sqlit
11960 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c e3_malloc()] wil
11970 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 l be used to obt
11980 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e ain the memory n
11990 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a eeded.</dd>.**.*
119a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
119b0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
119c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
119d0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
119e0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
119f0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 ion specifies a
11a00 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 static memory bu
11a10 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 ffer that SQLite
11a20 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 can use for.**
11a30 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
11a40 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 e cache with the
11a50 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 default page ca
11a60 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
11a70 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f on. .** This co
11a80 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 nfiguration shou
11a90 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 ld not be used i
11aa0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
11ab0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 -define page.**
11ac0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
11ad0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 tion is loaded u
11ae0 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f sing the SQLITE_
11af0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f CONFIG_PCACHE2 o
11b00 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 ption..** There
11b10 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
11b20 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
11b30 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f on: A pointer to
11b40 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 8-byte aligned.
11b50 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 ** memory, the s
11b60 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 ize of each page
11b70 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e buffer (sz), an
11b80 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
11b90 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 pages (N)..** Th
11ba0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 e sz argument sh
11bb0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 ould be the size
11bc0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
11bd0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a database page.**
11be0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f (a power of two
11bf0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 between 512 and
11c00 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 32768) plus a l
11c10 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 ittle extra for
11c20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 each.** page hea
11c30 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 der. ^The page
11c40 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 header size is 2
11c50 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 0 to 40 bytes de
11c60 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 pending on.** th
11c70 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 e host architect
11c80 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 ure. ^It is har
11c90 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f mless, apart fro
11ca0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d m the wasted mem
11cb0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 ory,.** to make
11cc0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 sz a little too
11cd0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 large. The firs
11ce0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 t.** argument sh
11cf0 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e ould point to an
11d00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 allocation of a
11d10 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
11d20 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
11d30 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
11d40 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f e the memory pro
11d50 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 vided by the fir
11d60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
11d70 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 atisfy its.** me
11d80 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 mory needs for t
11d90 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 he first N pages
11da0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f that it adds to
11db0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 cache. ^If add
11dc0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 itional.** page
11dd0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 cache memory is
11de0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 needed beyond wh
11df0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 at is provided b
11e00 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 y this option, t
11e10 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f hen.** SQLite go
11e20 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d es to [sqlite3_m
11e30 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 alloc()] for the
11e40 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 additional stor
11e50 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 age space..** Th
11e60 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 e pointer in the
11e70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
11e80 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e must.** be align
11e90 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
11ea0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 boundary or subs
11eb0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
11ec0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c of SQLite.** wil
11ed0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c l be undefined.<
11ee0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
11ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
11f00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
11f10 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
11f20 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
11f30 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
11f40 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
11f50 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 fer that SQLite
11f60 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 will use.** for
11f70 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d all of its dynam
11f80 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ic memory alloca
11f90 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e tion needs beyon
11fa0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 d those provided
11fb0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 .** for by [SQLI
11fc0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
11fd0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 H] and [SQLITE_C
11fe0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
11ff0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 ..** There are t
12000 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 hree arguments:
12010 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 An 8-byte aligne
12020 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 d pointer to the
12030 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 memory,.** the
12040 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
12050 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
12060 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
12070 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
12080 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 size..** ^If th
12090 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
120a0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
120b0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
120c0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
120d0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
120e0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
120f0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
12100 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
12110 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
12120 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
12130 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
12140 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
12150 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 IG_MALLOC]. ^If
12160 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
12170 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
12180 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 LL and either [S
12190 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
121a0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c SYS3] or.** [SQL
121b0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
121c0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c S5] are defined,
121d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
121e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
121f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
12200 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
12210 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
12220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12230 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 needs..** The fi
12240 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
12250 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
12260 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
12270 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
12280 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
12290 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
122a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
122b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a be undefined..**
122c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c The minimum all
122d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 ocation size is
122e0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e capped at 2**12.
122f0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 Reasonable valu
12300 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 es.** for the mi
12310 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
12320 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 size are 2**5 t
12330 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 hrough 2**8.</dd
12340 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12350 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 _CONFIG_MUTEX]]
12360 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
12370 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 G_MUTEX</dt>.**
12380 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
12390 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
123a0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
123b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
123c0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
123d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
123e0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
123f0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 tructure. The a
12400 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
12410 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 s.** alternative
12420 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 low-level mutex
12430 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
12440 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a used in place.**
12450 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 the mutex routi
12460 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
12470 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 QLite.)^ ^SQLit
12480 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
12490 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 f the.** content
124a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
124b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
124c0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 structure before
124d0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
124e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
124f0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 )] returns. ^If
12500 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
12510 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
12520 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
12530 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
12540 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
12550 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
12560 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
12570 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
12580 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
12590 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
125a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
125b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
125c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
125d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
125e0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
125f0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
12600 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
12610 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
12620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12630 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 G_GETMUTEX]] <dt
12640 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
12650 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
12660 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 <dd> ^(This opti
12670 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12680 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12690 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
126a0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 an.** instance
126b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
126c0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
126d0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
126e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
126f0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
12700 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
12710 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
12720 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
12730 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
12740 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
12750 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
12760 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
12770 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
12780 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
12790 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
127a0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
127b0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
127c0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
127d0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
127e0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
127f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
12800 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
12810 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
12820 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
12830 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
12840 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
12850 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
12860 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
12870 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
12880 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
12890 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
128a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
128b0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
128c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
128d0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
128e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
128f0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
12900 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
12910 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
12920 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
12930 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
12940 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
12950 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
12960 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 his option takes
12970 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 two arguments t
12980 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
12990 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d e default.** mem
129a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
129b0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 or the lookaside
129c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
129d0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 r on each.** [da
129e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
129f0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 n]. The first a
12a00 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
12a10 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
12a20 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
12a30 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
12a40 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
12a50 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
12a60 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
12a70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12a80 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f ion.)^ ^(This o
12a90 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
12aa0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e * <i>default</i>
12ab0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
12ac0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
12ad0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
12ae0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c .** verb to [sql
12af0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
12b00 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
12b10 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
12b20 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
12b30 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
12b40 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
12b50 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
12b60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
12b70 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 PCACHE2]] <dt>SQ
12b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
12b90 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
12ba0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 ^(This option t
12bb0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
12bc0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
12bd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 a pointer to.**
12be0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 an [sqlite3_pcac
12bf0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
12c00 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 ect. This objec
12c10 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 t specifies the
12c20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 interface.** to
12c30 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 a custom page ca
12c40 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 che implementati
12c50 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d on.)^ ^SQLite m
12c60 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
12c70 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 he.** object and
12c80 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 uses it for pag
12c90 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 e cache memory a
12ca0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e llocations.</dd>
12cb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
12cc0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
12cd0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 2]] <dt>SQLITE_C
12ce0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
12cf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
12d00 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
12d10 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
12d20 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 ent which is a p
12d30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
12d40 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f [sqlite3_pcache_
12d50 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 methods2] object
12d60 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 . SQLite copies
12d70 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
12d80 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d ** page cache im
12d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 plementation int
12da0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e o that object.)^
12db0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
12dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
12dd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
12de0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a NFIG_LOG</dt>.**
12df0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
12e00 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
12e10 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 ion takes two ar
12e20 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 guments: a point
12e30 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 er to a.** funct
12e40 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 ion with a call
12e50 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 signature of voi
12e60 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 d(*)(void*,int,c
12e70 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a onst char*), .**
12e80 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 and a pointer t
12e90 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 o void. ^If the
12ea0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
12eb0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 is not NULL, it
12ec0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 is.** invoked b
12ed0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 y [sqlite3_log()
12ee0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 ] to process eac
12ef0 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e h logging event.
12f00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e ^If the.** fun
12f10 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 ction pointer is
12f20 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 NULL, the [sqli
12f30 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 te3_log()] inter
12f40 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e face becomes a n
12f50 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f o-op..** ^The vo
12f60 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 id pointer that
12f70 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 is the second ar
12f80 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 gument to SQLITE
12f90 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a _CONFIG_LOG is.*
12fa0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 * passed through
12fb0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 as the first pa
12fc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
12fd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
12fe0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
12ff0 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 ction whenever t
13000 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 hat function is
13010 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 invoked. ^The s
13020 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
13030 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 to.** the logger
13040 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 function is a c
13050 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 opy of the first
13060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
13070 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a e corresponding.
13080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 ** [sqlite3_log(
13090 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 )] call and is i
130a0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 ntended to be a
130b0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 [result code] or
130c0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 an.** [extended
130d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 result code].
130e0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d ^The third param
130f0 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 eter passed to t
13100 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 he logger is.**
13110 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 log message afte
13120 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 r formatting via
13130 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
13140 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 tf()]..** The SQ
13150 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 Lite logging int
13160 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 erface is not re
13170 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 entrant; the log
13180 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ger function.**
13190 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 supplied by the
131a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
131b0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 not invoke any
131c0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
131d0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d ..** In a multi-
131e0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 threaded applica
131f0 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 tion, the applic
13200 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f ation-defined lo
13210 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gger.** function
13220 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
13230 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a afe. </dd>.**.**
13240 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
13250 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _URI]] <dt>SQLIT
13260 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 E_CONFIG_URI.**
13270 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e <dd> This option
13280 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
13290 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 argument of type
132a0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 int. If non-zer
132b0 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 o, then.** URI h
132c0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
132d0 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 lly enabled. If
132e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
132f0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 zero, then URI
13300 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 handling.** is g
13310 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 lobally disabled
13320 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e . If URI handlin
13330 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e g is globally en
13340 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e abled, all filen
13350 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 ames.** passed t
13360 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 o [sqlite3_open(
13370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 )], [sqlite3_ope
13380 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 n_v2()], [sqlite
13390 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 3_open16()] or.*
133a0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 * specified as p
133b0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 art of [ATTACH]
133c0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 commands are int
133d0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
133e0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 , regardless.**
133f0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
13400 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 t the [SQLITE_OP
13410 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 EN_URI] flag is
13420 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 set when the dat
13430 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
13440 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 ion is opened. I
13450 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 f it is globally
13460 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e disabled, filen
13470 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 ames are.** only
13480 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
13490 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 URIs if the SQLI
134a0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 TE_OPEN_URI flag
134b0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
134c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
134d0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
134e0 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 d. By default, U
134f0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
13500 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 lobally.** disab
13510 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 led. The default
13520 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 value may be ch
13530 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 anged by compili
13540 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ng with the.** [
13550 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
13560 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a symbol defined..
13570 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
13580 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
13590 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e NDEX_SCAN]] <dt>
135a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
135b0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
135c0 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f N.** <dd> This o
135d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
135e0 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 ngle integer arg
135f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 ument which is i
13600 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a nterpreted as.**
13610 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 a boolean in or
13620 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 der to enable or
13630 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 disable the use
13640 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 of covering ind
13650 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c ices for.** full
13660 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 table scans in
13670 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 the query optimi
13680 7a 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c zer. The defaul
13690 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 t setting is det
136a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 ermined.** by th
136b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f e [SQLITE_ALLOW_
136c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
136d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d CAN] compile-tim
136e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 e option, or is
136f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 "on".** if that
13700 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
13710 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ion is omitted..
13720 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 ** The ability t
13730 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 o disable the us
13740 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e e of covering in
13750 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 dices for full t
13760 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 able scans.** is
13770 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e because some in
13780 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 correctly coded
13790 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 legacy applicati
137a0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e ons might malfun
137b0 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 ction.** malfunc
137c0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 tion when the op
137d0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e timization is en
137e0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e abled. Providin
137f0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f g the ability to
13800 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 .** disable the
13810 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c optimization all
13820 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 ows the older, b
13830 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e uggy application
13840 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a code to work.**
13850 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 without change
13860 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 even with newer
13870 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
13880 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 te..**.** [[SQLI
13890 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
138a0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ]] [[SQLITE_CONF
138b0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a IG_GETPCACHE]].*
138c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
138d0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 FIG_PCACHE and S
138e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
138f0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 PCACHE.** <dd> T
13900 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 hese options are
13910 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 obsolete and sh
13920 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 ould not be used
13930 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a by new code..**
13940 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e They are retain
13950 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
13960 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 compatibility b
13970 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 ut are now no-op
13980 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a s..** </dl>.**.*
13990 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
139a0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 G_SQLLOG]].** <d
139b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
139c0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 SQLLOG.** <dd>Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c is option is onl
139e0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 y available if s
139f0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 qlite is compile
13a00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 d with the.** SQ
13a10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c LITE_ENABLE_SQLL
13a20 4f 47 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 OG pre-processor
13a30 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 macro defined.
13a40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
13a50 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 nt should.** be
13a60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 a pointer to a f
13a70 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
13a80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
13a90 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 lite3*,const cha
13aa0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 r*, int)..** The
13ab0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 second should b
13ac0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a e of type (void*
13ad0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ). The callback
13ae0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 is invoked by th
13af0 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 e library.** in
13b00 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 three separate c
13b10 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 ircumstances, id
13b20 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
13b30 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
13b40 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
13b50 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 rameter. If the
13b60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
13b70 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 is 0, then the
13b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13b90 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 ion.** passed as
13ba0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
13bb0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 ment has just be
13bc0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 en opened. The t
13bd0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
13be0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 points to a buf
13bf0 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 fer containing t
13c00 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
13c10 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
13c20 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 e. If the.** fou
13c30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
13c40 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 1, then the SQL
13c50 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
13c60 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
13c70 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ter.** points to
13c80 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 has just been e
13c90 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 xecuted. Or, if
13ca0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
13cb0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a eter is 2, then.
13cc0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ** the connectio
13cd0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 n being passed a
13ce0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
13cf0 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 ameter is being
13d00 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 closed. The.** t
13d10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
13d20 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e s passed NULL In
13d30 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c this case..** <
13d40 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
13d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 SQLITE_CONFIG_SI
13d60 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f NGLETHREAD 1 /
13d70 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
13d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
13d90 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 ULTITHREAD 2
13da0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
13db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13dc0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 SERIALIZED 3
13dd0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
13de0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
13df0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 _MALLOC 4
13e00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
13e10 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
13e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
13e30 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 IG_GETMALLOC
13e40 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 5 /* sqlite3_m
13e50 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
13e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
13e70 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 NFIG_SCRATCH
13e80 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 6 /* void*,
13e90 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f int sz, int N */
13ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
13eb0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
13ec0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 7 /* void*
13ed0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
13ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
13ef0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 E_CONFIG_HEAP
13f00 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 8 /* voi
13f10 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 d*, int nByte, i
13f20 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e nt min */.#defin
13f30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
13f40 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 MEMSTATUS 9
13f50 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 /* boolean */.#
13f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
13f70 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 NFIG_MUTEX
13f80 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 10 /* sqlite3
13f90 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 _mutex_methods*
13fa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
13fb0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
13fc0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c X 11 /* sql
13fd0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13fe0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f ds* */./* previo
13ff0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 usly SQLITE_CONF
14000 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 IG_CHUNKALLOC 12
14010 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e which is now un
14020 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e used. */ .#defin
14030 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
14040 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 LOOKASIDE 13
14050 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 /* int int */.#
14060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
14070 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 NFIG_PCACHE
14080 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 14 /* no-op *
14090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
140a0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
140b0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f E 15 /* no-o
140c0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c p */.#define SQL
140d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 ITE_CONFIG_LOG
140e0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 16 /* x
140f0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 Func, void* */.#
14100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
14110 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 NFIG_URI
14120 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 17 /* int */.
14130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
14140 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 ONFIG_PCACHE2
14150 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 18 /* sqlite
14160 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
14170 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 2* */.#define SQ
14180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
14190 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 CACHE2 19 /*
141a0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
141b0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 ethods2* */.#def
141c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
141d0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
141e0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 _SCAN 20 /* int
141f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
14200 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
14210 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 21 /* xS
14220 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a qllog, void* */.
14230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
14240 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
14250 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 tion Configurati
14260 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a on Options.**.**
14270 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
14280 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 are the availab
14290 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 le integer confi
142a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
142b0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 that.** can be
142c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
142d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f cond argument to
142e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 the [sqlite3_db
142f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
14300 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
14310 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14320 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
14330 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
14340 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
14350 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
14360 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
14370 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
14380 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
14390 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
143a0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
143b0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
143c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
143d0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
143e0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
143f0 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b worked. ^The [
14400 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
14410 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
14420 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
14430 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
14440 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
14450 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
14460 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
14470 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
14480 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
14490 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c <dl>.** <dt>SQL
144a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
144b0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c KASIDE</dt>.** <
144c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
144d0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 takes three add
144e0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
144f0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
14500 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 the .** [lookas
14510 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ide memory alloc
14520 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 ator] configurat
14530 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 ion for the [dat
14540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14550 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 ]..** ^The first
14560 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 argument (the t
14570 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
14580 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f o [sqlite3_db_co
14590 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 nfig()] is a.**
145a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
145b0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 ory buffer to us
145c0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 e for lookaside
145d0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 memory..** ^The
145e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 first argument a
145f0 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f fter the SQLITE_
14600 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
14610 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 DE verb.** may b
14620 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 e NULL in which
14630 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c case SQLite will
14640 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a allocate the.**
14650 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
14660 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b r itself using [
14670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14680 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ]. ^The second a
14690 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
146a0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
146b0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
146c0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 slot. ^The thir
146d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
146e0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 e number of.** s
146f0 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 lots. The size
14700 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e of the buffer in
14710 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
14720 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 ent must be grea
14730 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 ter than.** or e
14740 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 qual to the prod
14750 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e uct of the secon
14760 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 d and third argu
14770 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 ments. The buff
14780 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c er.** must be al
14790 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 igned to an 8-by
147a0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 te boundary. ^I
147b0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 f the second arg
147c0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 ument to.** SQLI
147d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
147e0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d ASIDE is not a m
147f0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 ultiple of 8, it
14800 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a is internally.*
14810 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 * rounded down t
14820 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c o the next small
14830 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 er multiple of 8
14840 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 . ^(The lookasi
14850 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e de memory.** con
14860 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 figuration for a
14870 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
14880 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 tion can only be
14890 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 changed when th
148a0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e at.** connection
148b0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c is not currentl
148c0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 y using lookasid
148d0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 e memory, or in
148e0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 other words.** w
148f0 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 hen the "current
14900 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 value" returned
14910 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
14920 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 db_status](D,[SQ
14930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
14940 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a ASIDE],...) is z
14950 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 ero..** Any atte
14960 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 mpt to change th
14970 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f e lookaside memo
14980 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ry configuration
14990 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a when lookaside.
149a0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 ** memory is in
149b0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 use leaves the c
149c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 onfiguration unc
149d0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 hanged and retur
149e0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 ns .** [SQLITE_B
149f0 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a USY].)^</dd>.**.
14a00 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 ** <dt>SQLITE_DB
14a10 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
14a20 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EY</dt>.** <dd>
14a30 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
14a40 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
14a50 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e r disable the en
14a60 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 forcement of.**
14a70 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e [foreign key con
14a80 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 straints]. Ther
14a90 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
14aa0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
14ab0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
14ac0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
14ad0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
14ae0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
14af0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a FK enforcement,.
14b00 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
14b10 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 nable FK enforce
14b20 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 ment or negative
14b30 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 to leave FK enf
14b40 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 orcement.** unch
14b50 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f anged. The seco
14b60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
14b70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
14b80 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 integer into whi
14b90 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e ch.** is written
14ba0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 0 or 1 to indic
14bb0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 ate whether FK e
14bc0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 nforcement is of
14bd0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f f or on.** follo
14be0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 wing this call.
14bf0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
14c00 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e meter may be a N
14c10 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a ULL pointer, in.
14c20 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 ** which case th
14c30 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
14c40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
14c50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c reported back. <
14c60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 /dd>.**.** <dt>S
14c70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
14c80 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 NABLE_TRIGGER</d
14c90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
14ca0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
14cb0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
14cc0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 able [CREATE TRI
14cd0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d GGER | triggers]
14ce0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c ..** There shoul
14cf0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f d be two additio
14d00 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a nal arguments..*
14d10 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
14d20 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 ment is an integ
14d30 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f er which is 0 to
14d40 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 disable trigger
14d50 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 s,.** positive t
14d60 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 o enable trigger
14d70 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f s or negative to
14d80 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 leave the setti
14d90 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a ng unchanged..**
14da0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 The second para
14db0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 meter is a point
14dc0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
14dd0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 into which.** i
14de0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 s written 0 or 1
14df0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 to indicate whe
14e00 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 ther triggers ar
14e10 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e e disabled or en
14e20 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 abled.** followi
14e30 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 ng this call. T
14e40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
14e50 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c ter may be a NUL
14e60 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a L pointer, in.**
14e70 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 which case the
14e80 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 trigger setting
14e90 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
14ea0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a back. </dd>.**.*
14eb0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
14ec0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
14ed0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
14ee0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 1001 /* void
14ef0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 * int int */.#de
14f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
14f10 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 NFIG_ENABLE_FKEY
14f20 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 1002 /* in
14f30 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
14f40 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
14f50 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
14f60 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 1003 /* int i
14f70 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt* */.../*.** C
14f80 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 API3REF: Enable
14f90 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e Or Disable Exten
14fa0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 ded Result Codes
14fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
14fc0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
14fd0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 ult_codes() rout
14fe0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ine enables or d
14ff0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b isables the.** [
15000 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
15010 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f codes] feature o
15020 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 f SQLite. ^The e
15030 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a xtended result.*
15040 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 * codes are disa
15050 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
15060 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 for historical c
15070 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f ompatibility..*/
15080 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
15090 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
150a0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 _result_codes(sq
150b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 lite3*, int onof
150c0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 f);../*.** CAPI3
150d0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 REF: Last Insert
150e0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 Rowid.**.** ^Ea
150f0 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 ch entry in an S
15100 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 QLite table has
15110 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 a unique 64-bit
15120 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 signed.** intege
15130 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 r key called the
15140 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 [ROWID | "rowid
15150 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 "]. ^The rowid i
15160 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 s always availab
15170 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 le.** as an unde
15180 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 clared column na
15190 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 med ROWID, OID,
151a0 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f or _ROWID_ as lo
151b0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e ng as those.** n
151c0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 ames are not als
151d0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 o used by explic
151e0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f itly declared co
151f0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 lumns. ^If.** th
15200 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f e table has a co
15210 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e lumn of type [IN
15220 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 TEGER PRIMARY KE
15230 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c Y] then that col
15240 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 umn.** is anothe
15250 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 r alias for the
15260 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rowid..**.** ^Th
15270 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
15280 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f ns the [rowid] o
15290 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
152a0 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 t.** successful
152b0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 [INSERT] into th
152c0 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 e database from
152d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
152e0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 nnection].** in
152f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
15300 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 nt. ^As of SQLi
15310 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 te version 3.7.7
15320 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a , this routines.
15330 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c ** records the l
15340 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 ast insert rowid
15350 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 of both ordinar
15360 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 y tables and [vi
15370 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a rtual tables]..*
15380 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 * ^If no success
15390 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a ful [INSERT]s.**
153a0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 have ever occur
153b0 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 red on that data
153c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
153d0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 zero is returne
153e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e d..**.** ^(If an
153f0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 [INSERT] occurs
15400 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 within a trigge
15410 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 r or within a [v
15420 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a irtual table].**
15430 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 method, then th
15440 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 is routine will
15450 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 return the [rowi
15460 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 d] of the insert
15470 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e ed.** row as lon
15480 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 g as the trigger
15490 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c or virtual tabl
154a0 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e e method is runn
154b0 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 ing..** But once
154c0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 the trigger or
154d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 virtual table me
154e0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 thod ends, the v
154f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a alue returned .*
15500 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e * by this routin
15510 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 e reverts to wha
15520 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 t it was before
15530 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 the trigger or v
15540 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 irtual.** table
15550 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a method began.)^.
15560 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 **.** ^An [INSER
15570 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 T] that fails du
15580 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e e to a constrain
15590 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e t violation is n
155a0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 ot a.** successf
155b0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 ul [INSERT] and
155c0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 does not change
155d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
155e0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f ed by this.** ro
155f0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e utine. ^Thus IN
15600 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e SERT OR FAIL, IN
15610 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 SERT OR IGNORE,
15620 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 INSERT OR ROLLBA
15630 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 CK,.** and INSER
15640 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 T OR ABORT make
15650 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 no changes to th
15660 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f e return value o
15670 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e f this.** routin
15680 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 e when their ins
15690 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e ertion fails. ^
156a0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 (When INSERT OR
156b0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 REPLACE.** encou
156c0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 nters a constrai
156d0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 nt violation, it
156e0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 does not fail.
156f0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 The.** INSERT c
15700 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 ontinues to comp
15710 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c letion after del
15720 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 eting rows that
15730 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f caused.** the co
15740 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d nstraint problem
15750 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 so INSERT OR RE
15760 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 PLACE will alway
15770 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 s change.** the
15780 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
15790 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 this interface.)
157a0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 ^.**.** ^For the
157b0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 purposes of thi
157c0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 s routine, an [I
157d0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 NSERT] is consid
157e0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 ered to.** be su
157f0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 ccessful even if
15800 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e it is subsequen
15810 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e tly rolled back.
15820 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 .**.** This func
15830 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 tion is accessib
15840 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d le to SQL statem
15850 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 ents via the.**
15860 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 [last_insert_row
15870 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f id() SQL functio
15880 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
15890 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 eparate thread p
158a0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 erforms a new [I
158b0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 NSERT] on the sa
158c0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 me.** database c
158d0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 onnection while
158e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 the [sqlite3_las
158f0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
15900 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 ].** function is
15910 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 running and thu
15920 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 s changes the la
15930 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 st insert [rowid
15940 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 ],.** then the v
15950 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
15960 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
15970 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 nsert_rowid()] i
15980 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 s.** unpredictab
15990 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 le and might not
159a0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 equal either th
159b0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 e old or the new
159c0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 .** last insert
159d0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 [rowid]..*/.SQLI
159e0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
159f0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 nt64 sqlite3_las
15a00 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 t_insert_rowid(s
15a10 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
15a20 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 CAPI3REF: Count
15a30 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 The Number Of R
15a40 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a ows Modified.**.
15a50 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
15a60 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
15a70 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 mber of database
15a80 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 rows that were
15a90 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e changed.** or in
15aa0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 serted or delete
15ab0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 d by the most re
15ac0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 cently completed
15ad0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
15ae0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 * on the [databa
15af0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
15b00 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
15b10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e first parameter.
15b20 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 .** ^(Only chang
15b30 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 es that are dire
15b40 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 ctly specified b
15b50 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 y the [INSERT],
15b60 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 [UPDATE],.** or
15b70 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
15b80 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 nt are counted.
15b90 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 Auxiliary chang
15ba0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 es caused by.**
15bb0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 triggers or [for
15bc0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 eign key actions
15bd0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 ] are not counte
15be0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 d.)^ Use the.**
15bf0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 [sqlite3_total_c
15c00 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 hanges()] functi
15c10 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 on to find the t
15c20 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 otal number of c
15c30 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 hanges.** includ
15c40 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 ing changes caus
15c50 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 ed by triggers a
15c60 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 nd foreign key a
15c70 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 ctions..**.** ^C
15c80 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
15c90 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 that are simula
15ca0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 ted by an [INSTE
15cb0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a AD OF trigger].*
15cc0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 * are not counte
15cd0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 d. Only real ta
15ce0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 ble changes are
15cf0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e counted..**.** ^
15d00 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 (A "row change"
15d10 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 is a change to a
15d20 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 single row of a
15d30 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a single table.**
15d40 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e caused by an IN
15d50 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 SERT, DELETE, or
15d60 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e UPDATE statemen
15d70 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a t. Rows that.**
15d80 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 are changed as
15d90 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 side effects of
15da0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 [REPLACE] constr
15db0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c aint resolution,
15dc0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 .** rollback, AB
15dd0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 ORT processing,
15de0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 [DROP TABLE], or
15df0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by any other.**
15e00 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e mechanisms do n
15e10 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 ot count as dire
15e20 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 ct row changes.)
15e30 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 ^.**.** A "trigg
15e40 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 er context" is a
15e50 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 scope of execut
15e60 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 ion that begins
15e70 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 and.** ends with
15e80 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 the script of a
15e90 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
15ea0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a | trigger]. .**
15eb0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d Most SQL statem
15ec0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c ents are.** eval
15ed0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 uated outside of
15ee0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 any trigger. T
15ef0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 his is the "top
15f00 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 level".** trigge
15f10 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 r context. If a
15f20 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 trigger fires f
15f30 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 rom the top leve
15f40 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 l, a.** new trig
15f50 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 ger context is e
15f60 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 ntered for the d
15f70 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 uration of that
15f80 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 one.** trigger.
15f90 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 Subtriggers cre
15fa0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 ate subcontexts
15fb0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 for their durati
15fc0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 on..**.** ^Calli
15fd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ng [sqlite3_exec
15fe0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
15ff0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 step()] recursiv
16000 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 ely does.** not
16010 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 create a new tri
16020 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a gger context..**
16030 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
16040 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e on returns the n
16050 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 umber of direct
16060 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 row changes in t
16070 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e he.** most recen
16080 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 t INSERT, UPDATE
16090 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 , or DELETE stat
160a0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 ement within the
160b0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 same.** trigger
160c0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 context..**.**
160d0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c ^Thus, when call
160e0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 ed from the top
160f0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 level, this func
16100 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 tion returns the
16110 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 .** number of ch
16120 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 anges in the mos
16130 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c t recent INSERT,
16140 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 UPDATE, or DELE
16150 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 TE.** that also
16160 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 occurred at the
16170 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 top level. ^(Wi
16180 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 thin the body of
16190 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 a trigger,.** t
161a0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
161b0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 es() interface c
161c0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 an be called to
161d0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
161e0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e of.** changes in
161f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
16200 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
16210 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
16220 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d DELETE.** statem
16230 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 ent within the b
16240 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ody of the same
16250 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 trigger..** Howe
16260 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 ver, the number
16270 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f returned does no
16280 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 t include change
16290 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 s.** caused by s
162a0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 ubtriggers since
162b0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 those have thei
162c0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e r own context.)^
162d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
162e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
162f0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e al_changes()] in
16300 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
16310 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
16320 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
16330 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 [changes() SQL f
16340 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
16350 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
16360 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
16370 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
16380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16390 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
163a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
163b0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
163c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
163d0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
163e0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
163f0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
16400 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
16410 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c ite3_changes(sql
16420 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
16430 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e API3REF: Total N
16440 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f umber Of Rows Mo
16450 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 dified.**.** ^Th
16460 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 is function retu
16470 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
16480 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 f row changes ca
16490 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d used by [INSERT]
164a0 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 ,.** [UPDATE] or
164b0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d [DELETE] statem
164c0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b ents since the [
164d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
164e0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e ion] was opened.
164f0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 .** ^(The count
16500 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
16510 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
16520 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c s() includes all
16530 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d changes.** from
16540 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 all [CREATE TRI
16550 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 GGER | trigger]
16560 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 contexts and cha
16570 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 nges made by.**
16580 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
16590 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a ions]. However,.
165a0 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 ** the count doe
165b0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 s not include ch
165c0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d anges used to im
165d0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 plement [REPLACE
165e0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a ] constraints,.*
165f0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f * do rollbacks o
16600 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 r ABORT processi
16610 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 ng, or [DROP TAB
16620 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 LE] processing.
16630 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f The.** count do
16640 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 es not include r
16650 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 ows of views tha
16660 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 t fire an [INSTE
16670 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a AD OF trigger],.
16680 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 ** though if the
16690 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 INSTEAD OF trig
166a0 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ger makes change
166b0 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 s of its own, th
166c0 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 ose changes .**
166d0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a are counted.)^.*
166e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 * ^The sqlite3_t
166f0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 otal_changes() f
16700 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 unction counts t
16710 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f he changes as so
16720 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 on as.** the sta
16730 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 tement that make
16740 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 s them is comple
16750 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 ted (when the st
16760 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a atement handle.*
16770 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b * is passed to [
16780 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
16790 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
167a0 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a alize()])..**.**
167b0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
167c0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
167d0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
167e0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
167f0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
16800 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 the [total_chang
16810 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
16820 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
16830 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
16840 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
16850 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
16860 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
16870 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 while [sqlite3_t
16880 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
16890 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
168a0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 the value.** ret
168b0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 urned is unpredi
168c0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
168d0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 eaningful..*/.SQ
168e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
168f0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
16900 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f es(sqlite3*);../
16910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
16920 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d nterrupt A Long-
16930 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a Running Query.**
16940 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
16950 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 on causes any pe
16960 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f nding database o
16970 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 peration to abor
16980 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 t and.** return
16990 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 at its earliest
169a0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 opportunity. Thi
169b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 s routine is typ
169c0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 ically.** called
169d0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 in response to
169e0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 a user action su
169f0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 ch as pressing "
16a00 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 Cancel".** or Ct
16a10 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 rl-C where the u
16a20 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 ser wants a long
16a30 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e query operation
16a40 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 to halt.** imme
16a50 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e diately..**.** ^
16a60 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 It is safe to ca
16a70 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ll this routine
16a80 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 from a thread di
16a90 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 fferent from the
16aa0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 .** thread that
16ab0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e is currently run
16ac0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
16ad0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 e operation. Bu
16ae0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 t it.** is not s
16af0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 afe to call this
16b00 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 routine with a
16b10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
16b20 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 tion] that.** is
16b30 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 closed or might
16b40 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 close before sq
16b50 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
16b60 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a ) returns..**.**
16b70 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 ^If an SQL oper
16b80 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 ation is very ne
16b90 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 arly finished at
16ba0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a the time when.*
16bb0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 * sqlite3_interr
16bc0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c upt() is called,
16bd0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e then it might n
16be0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 ot have an oppor
16bf0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 tunity.** to be
16c00 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 interrupted and
16c10 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 might continue t
16c20 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a o completion..**
16c30 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 .** ^An SQL oper
16c40 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e ation that is in
16c50 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 terrupted will r
16c60 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e eturn [SQLITE_IN
16c70 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 TERRUPT]..** ^If
16c80 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 the interrupted
16c90 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 SQL operation i
16ca0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 s an INSERT, UPD
16cb0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a ATE, or DELETE.*
16cc0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 * that is inside
16cd0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 an explicit tra
16ce0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 nsaction, then t
16cf0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 he entire transa
16d00 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 ction.** will be
16d10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 rolled back aut
16d20 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a omatically..**.*
16d30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
16d40 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c nterrupt(D) call
16d50 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e is in effect un
16d60 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c til all currentl
16d70 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c y running.** SQL
16d80 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b statements on [
16d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16da0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e ion] D complete.
16db0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 ^Any new SQL s
16dc0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
16dd0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
16de0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
16df0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
16e00 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 and before the
16e10 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 .** running stat
16e20 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a ements reaches z
16e30 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 ero are interrup
16e40 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 ted as if they h
16e50 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 ad been.** runni
16e60 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 ng prior to the
16e70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
16e80 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 t() call. ^New
16e90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
16ea0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
16eb0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e ed after the run
16ec0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 ning statement c
16ed0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 ount reaches zer
16ee0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 o are.** not eff
16ef0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c ected by the sql
16f00 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
16f10 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 ..** ^A call to
16f20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
16f30 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 t(D) that occurs
16f40 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 when there are
16f50 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 no running.** SQ
16f60 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 L statements is
16f70 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 a no-op and has
16f80 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c no effect on SQL
16f90 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
16fa0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
16fb0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 after the sqlite
16fc0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
16fd0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ll returns..**.*
16fe0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 * If the databas
16ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f e connection clo
17000 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 ses while [sqlit
17010 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a e3_interrupt()].
17020 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 ** is running th
17030 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 en bad things wi
17040 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e ll likely happen
17050 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
17060 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 void sqlite3_int
17070 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 errupt(sqlite3*)
17080 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
17090 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
170a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
170b0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a Is Complete.**.
170c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
170d0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 s are useful dur
170e0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 ing command-line
170f0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d input to determ
17100 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 ine if the.** cu
17110 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 rrently entered
17120 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f text seems to fo
17130 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 rm a complete SQ
17140 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a L statement or.*
17150 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 * if additional
17160 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 input is needed
17170 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 before sending t
17180 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 he text into.**
17190 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 SQLite for parsi
171a0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 ng. ^These rout
171b0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 ines return 1 if
171c0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
171d0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 g.** appears to
171e0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 be a complete SQ
171f0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 L statement. ^A
17200 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 statement is ju
17210 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f dged to be.** co
17220 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 mplete if it end
17230 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c s with a semicol
17240 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 on token and is
17250 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 not a prefix of
17260 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 a.** well-formed
17270 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 CREATE TRIGGER
17280 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d statement. ^Sem
17290 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 icolons that are
172a0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e embedded within
172b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 .** string liter
172c0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 als or quoted id
172d0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f entifier names o
172e0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e r comments are n
172f0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e ot.** independen
17300 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 t tokens (they a
17310 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 re part of the t
17320 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 oken in which th
17330 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 ey are.** embedd
17340 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 ed) and thus do
17350 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 not count as a s
17360 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 tatement termina
17370 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 tor. ^Whitespac
17380 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 e.** and comment
17390 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 s that follow th
173a0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f e final semicolo
173b0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a n are ignored..*
173c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
173d0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 ines return 0 if
173e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
173f0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e s incomplete. ^
17400 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 If a.** memory a
17410 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c llocation fails,
17420 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d then SQLITE_NOM
17430 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a EM is returned..
17440 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
17450 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 tines do not par
17460 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 se the SQL state
17470 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 ments thus.** wi
17480 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 ll not detect sy
17490 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f ntactically inco
174a0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a rrect SQL..**.**
174b0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 ^(If SQLite has
174c0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 not been initia
174d0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c lized using [sql
174e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
174f0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 )] prior .** to
17500 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 invoking sqlite3
17510 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 _complete16() th
17520 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 en sqlite3_initi
17530 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
17540 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 ed.** automatica
17550 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 lly by sqlite3_c
17560 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 omplete16(). If
17570 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 that initializa
17580 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 tion fails,.** t
17590 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 hen the return v
175a0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
175b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 3_complete16() w
175c0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a ill be non-zero.
175d0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ** regardless of
175e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
175f0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 the input SQL is
17600 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a complete.)^.**.
17610 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
17620 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
17630 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a e()] must be a z
17640 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
17650 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a * UTF-8 string..
17660 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 **.** The input
17670 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 to [sqlite3_comp
17680 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 lete16()] must b
17690 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 e a zero-termina
176a0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 ted.** UTF-16 st
176b0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 ring in native b
176c0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 yte order..*/.SQ
176d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
176e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f ite3_complete(co
176f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a nst char *sql);.
17700 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
17710 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
17720 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6(const void *sq
17730 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
17740 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 REF: Register A
17750 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 Callback To Hand
17760 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 le SQLITE_BUSY E
17770 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 rrors.**.** ^Thi
17780 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 s routine sets a
17790 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
177a0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 on that might be
177b0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 invoked wheneve
177c0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 r.** an attempt
177d0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 is made to open
177e0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
177f0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 that another th
17800 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 read.** or proce
17810 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a ss has locked..*
17820 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 *.** ^If the bus
17830 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
17840 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
17850 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 _BUSY] or [SQLIT
17860 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d E_IOERR_BLOCKED]
17870 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
17880 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e immediately upon
17890 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 encountering th
178a0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 e lock. ^If the
178b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a busy callback.*
178c0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 * is not NULL, t
178d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
178e0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
178f0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d d with two argum
17900 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
17910 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
17920 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 to the busy hand
17930 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ler is a copy of
17940 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 the void* point
17950 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 er which.** is t
17960 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
17970 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 t to sqlite3_bus
17980 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 y_handler(). ^T
17990 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
179a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 nt to.** the bus
179b0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 y handler callba
179c0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ck is the number
179d0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 of times that t
179e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
179f0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f has.** been invo
17a00 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 ked for this loc
17a10 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 king event. ^If
17a20 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c the.** busy cal
17a30 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c lback returns 0,
17a40 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f then no additio
17a50 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 nal attempts are
17a60 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 made to.** acce
17a70 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ss the database
17a80 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 and [SQLITE_BUSY
17a90 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 ] or [SQLITE_IOE
17aa0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 RR_BLOCKED] is r
17ab0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 eturned..** ^If
17ac0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
17ad0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
17ae0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 hen another atte
17af0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 mpt.** is made t
17b00 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
17b10 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ase for reading
17b20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 and the cycle re
17b30 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 peats..**.** The
17b40 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 presence of a b
17b50 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 usy handler does
17b60 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 not guarantee t
17b70 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 hat it will be i
17b80 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 nvoked.** when t
17b90 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e here is lock con
17ba0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c tention. ^If SQL
17bb0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 ite determines t
17bc0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 hat invoking the
17bd0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 busy.** handler
17be0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e could result in
17bf0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 a deadlock, it
17c00 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e will go ahead an
17c10 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 d return [SQLITE
17c20 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 _BUSY].** or [SQ
17c30 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
17c40 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 ED] instead of i
17c50 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
17c60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e handler..** Con
17c70 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f sider a scenario
17c80 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 where one proce
17c90 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
17ca0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a read lock that.*
17cb0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 * it is trying t
17cc0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 o promote to a r
17cd0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 eserved lock and
17ce0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f .** a second pro
17cf0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
17d00 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
17d10 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e that it is tryin
17d20 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 g.** to promote
17d30 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 to an exclusive
17d40 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 lock. The first
17d50 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 process cannot
17d60 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 proceed.** becau
17d70 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
17d80 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
17d90 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 nd the second pr
17da0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 ocess cannot.**
17db0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 proceed because
17dc0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
17dd0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 the first. If
17de0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a both processes.*
17df0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 * invoke the bus
17e00 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 y handlers, neit
17e10 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e her will make an
17e20 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 y progress. The
17e30 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 refore,.** SQLit
17e40 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
17e50 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 E_BUSY] for the
17e60 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 first process, h
17e70 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a oping that this.
17e80 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 ** will induce t
17e90 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
17ea0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 to release its
17eb0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c read lock and al
17ec0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e low.** the secon
17ed0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f d process to pro
17ee0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ceed..**.** ^The
17ef0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 default busy ca
17f00 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a llback is NULL..
17f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 **.** ^The [SQLI
17f20 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 TE_BUSY] error i
17f30 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b s converted to [
17f40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f SQLITE_IOERR_BLO
17f50 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 CKED].** when SQ
17f60 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d Lite is in the m
17f70 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 iddle of a large
17f80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 transaction whe
17f90 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 re all the.** ch
17fa0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 anges will not f
17fb0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d it into the in-m
17fc0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 emory cache. SQ
17fd0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 Lite will.** alr
17fe0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 eady hold a RESE
17ff0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 RVED lock on the
18000 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 database file,
18010 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 but it needs.**
18020 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 to promote this
18030 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 lock to EXCLUSIV
18040 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e E so that it can
18050 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 spill cache.**
18060 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 pages into the d
18070 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 atabase file wit
18080 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e hout harm to con
18090 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 current.** reade
180a0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 rs. ^If it is u
180b0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 nable to promote
180c0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 the lock, then
180d0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a the in-memory.**
180e0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c cache will be l
180f0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 eft in an incons
18100 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 istent state and
18110 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a so the error.**
18120 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 code is promote
18130 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 d from the relat
18140 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 ively benign [SQ
18150 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a LITE_BUSY] to.**
18160 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 the more severe
18170 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 [SQLITE_IOERR_B
18180 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 LOCKED]. ^This
18190 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f error code promo
181a0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 tion.** forces a
181b0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c n automatic roll
181c0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e back of the chan
181d0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ges. See the.**
181e0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 <a href="/cvstr
181f0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 ac/wiki?p=Corrup
18200 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 tionFollowingBus
18210 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 yError">.** Corr
18220 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 uptionFollowingB
18230 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b usyError</a> wik
18240 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 i page for a dis
18250 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a cussion of why.*
18260 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 * this is import
18270 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ant..**.** ^(The
18280 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
18290 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
182a0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 dler defined for
182b0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 each.** [databa
182c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
182d0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 Setting a new b
182e0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 usy handler clea
182f0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f rs any.** previo
18300 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 usly set handler
18310 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 .)^ ^Note that
18320 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
18330 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
18340 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 .** will also se
18350 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 t or clear the b
18360 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a usy handler..**.
18370 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c ** The busy call
18380 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 back should not
18390 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 take any actions
183a0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 which modify th
183b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
183c0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
183d0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
183e0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 andler. Any suc
183f0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 h actions.** res
18400 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 ult in undefined
18410 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a behavior..** .*
18420 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 * A busy handler
18430 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
18440 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
18450 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 nection.** or [p
18460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
18470 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 t] that invoked
18480 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
18490 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
184a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
184b0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
184c0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
184d0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
184e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
184f0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
18500 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f t.**.** ^This ro
18510 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 utine sets a [sq
18520 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
18530 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 er | busy handle
18540 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a r] that sleeps.*
18550 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 * for a specifie
18560 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 d amount of time
18570 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 when a table is
18580 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 locked. ^The h
18590 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
185a0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
185b0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
185c0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
185d0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
185e0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
185f0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 ated. ^After at
18600 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
18610 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
18620 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e ping,.** the han
18630 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
18640 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c hich causes [sql
18650 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 ite3_step()] to
18660 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
18670 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 E_BUSY] or [SQLI
18680 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 TE_IOERR_BLOCKED
18690 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e ]..**.** ^Callin
186a0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 g this routine w
186b0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 ith an argument
186c0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 less than or equ
186d0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 al to zero.** tu
186e0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 rns off all busy
186f0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a handlers..**.**
18700 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c ^(There can onl
18710 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 y be a single bu
18720 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 sy handler for a
18730 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b particular.** [
18740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18750 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 ion] any any giv
18760 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 en moment. If a
18770 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 nother busy hand
18780 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e ler.** was defin
18790 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 ed (using [sqli
187a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
187b0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 ()]) prior to ca
187c0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f lling.** this ro
187d0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 utine, that othe
187e0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 r busy handler i
187f0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a s cleared.)^.*/.
18800 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
18810 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
18820 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
18830 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
18840 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
18850 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
18860 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
18870 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 .**.** This is a
18880 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
18890 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 e that is preser
188a0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ved for backward
188b0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
188c0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 .** Use of this
188d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
188e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a recommended..**
188f0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 .** Definition:
18900 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c A <b>result tabl
18910 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 e</b> is memory
18920 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 data structure c
18930 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a reated by the.**
18940 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 [sqlite3_get_ta
18950 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ble()] interface
18960 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c . A result tabl
18970 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a e records the.**
18980 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 complete query
18990 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 results from one
189a0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 or more queries
189b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c ..**.** The tabl
189c0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 e conceptually h
189d0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 as a number of r
189e0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e ows and columns.
189f0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e But.** these n
18a00 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 umbers are not p
18a10 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c art of the resul
18a20 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 t table itself.
18a30 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 These.** number
18a40 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 s are obtained s
18a50 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 eparately. Let
18a60 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 N be the number
18a70 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d of rows.** and M
18a80 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
18a90 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a f columns..**.**
18aa0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
18ab0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
18ac0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d ointers to zero-
18ad0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 terminated UTF-8
18ae0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 strings..** The
18af0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 re are (N+1)*M e
18b00 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 lements in the a
18b10 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 rray. The first
18b20 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e M pointers poin
18b30 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 t.** to zero-ter
18b40 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 minated strings
18b50 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 that contain th
18b60 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 e names of the c
18b70 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 olumns..** The r
18b80 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 emaining entries
18b90 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 all point to qu
18ba0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 ery results. NU
18bb0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 LL values result
18bc0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e .** in NULL poin
18bd0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 ters. All other
18be0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 values are in t
18bf0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d heir UTF-8 zero-
18c00 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
18c10 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 ring representat
18c20 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 ion as returned
18c30 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
18c40 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a mn_text()]..**.*
18c50 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
18c60 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f might consist o
18c70 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 f one or more me
18c80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 mory allocations
18c90 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 ..** It is not s
18ca0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 afe to pass a re
18cb0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 sult table direc
18cc0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f tly to [sqlite3_
18cd0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 free()]..** A re
18ce0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c sult table shoul
18cf0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 d be deallocated
18d00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
18d10 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a free_table()]..*
18d20 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 *.** ^(As an exa
18d30 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 mple of the resu
18d40 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c lt table format,
18d50 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 suppose a query
18d60 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 result.** is as
18d70 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
18d80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
18d90 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 >.** Name
18da0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a | Age.**
18db0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d --------
18dc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a ---------------.
18dd0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 ** Alice
18de0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 | 43.**
18df0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 Bob
18e00 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 | 28.**
18e10 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 Cindy | 21
18e20 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
18e30 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
18e40 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 ere are two colu
18e50 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 mn (M==2) and th
18e60 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e ree rows (N==3).
18e70 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 Thus the.** re
18e80 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 sult table has 8
18e90 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f entries. Suppo
18ea0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 se the result ta
18eb0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a ble is stored.**
18ec0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d in an array nam
18ed0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 es azResult. Th
18ee0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 en azResult hold
18ef0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a s this content:.
18f00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
18f10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 e><pre>.**
18f20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 azResult[0
18f30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 ] = "Name";.**
18f40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
18f50 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 91;1] = "Age";.*
18f60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
18f70 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 t[2] = "Alic
18f80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a e";.** az
18f90 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 Result[3] =
18fa0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 "43";.**
18fb0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 azResult[4]
18fc0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 = "Bob";.**
18fd0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
18fe0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 5] = "28";.**
18ff0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
19000 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 1;6] = "Cindy";.
19010 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
19020 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 lt[7] = "21"
19030 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
19040 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
19050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 ^The sqlite3_ge
19060 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 t_table() functi
19070 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 on evaluates one
19080 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 or more.** semi
19090 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 colon-separated
190a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 SQL statements i
190b0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 n the zero-termi
190c0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 nated UTF-8.** s
190d0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 tring of its 2nd
190e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 parameter and r
190f0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 eturns a result
19100 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 table to the.**
19110 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e pointer given in
19120 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 its 3rd paramet
19130 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 er..**.** After
19140 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
19150 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
19160 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f h the result fro
19170 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 m sqlite3_get_ta
19180 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 ble(),.** it mus
19190 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c t pass the resul
191a0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 t table pointer
191b0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f to sqlite3_free_
191c0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 table() in order
191d0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 to.** release t
191e0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 he memory that w
191f0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 as malloced. Be
19200 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 cause of the way
19210 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
19220 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 _malloc()] happe
19230 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 ns within sqlite
19240 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 3_get_table(), t
19250 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 he calling.** fu
19260 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 nction must not
19270 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c try to call [sql
19280 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 ite3_free()] dir
19290 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 ectly. Only.**
192a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 [sqlite3_free_ta
192b0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 ble()] is able t
192c0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 o release the me
192d0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e mory properly an
192e0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 d safely..**.**
192f0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f The sqlite3_get_
19300 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 table() interfac
19310 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 e is implemented
19320 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 as a wrapper ar
19330 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
19340 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 _exec()]. The s
19350 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
19360 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 () routine does
19370 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a not have access.
19380 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e ** to any intern
19390 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 al data structur
193a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 es of SQLite. I
193b0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 t uses only the
193c0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 public.** interf
193d0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 ace defined here
193e0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 . As a conseque
193f0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 nce, errors that
19400 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a occur in the.**
19410 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f wrapper layer o
19420 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e utside of the in
19430 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f ternal [sqlite3_
19440 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 exec()] call are
19450 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 not.** reflecte
19460 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 d in subsequent
19470 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
19480 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 3_errcode()] or.
19490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d ** [sqlite3_errm
194a0 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 sg()]..*/.SQLITE
194b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
194c0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
194d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
194e0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
194f0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
19500 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
19510 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
19520 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
19530 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
19540 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
19550 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
19560 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
19570 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
19580 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
19590 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
195a0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
195b0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
195c0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
195d0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
195e0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
195f0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
19600 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
19610 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c n here */.);.SQL
19620 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
19630 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 ite3_free_table(
19640 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a char **result);.
19650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
19660 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e Formatted Strin
19670 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 g Printing Funct
19680 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
19690 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f routines are wo
196a0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 rk-alikes of the
196b0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 "printf()" fami
196c0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a ly of functions.
196d0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e ** from the stan
196e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a dard C library..
196f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
19700 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 e3_mprintf() and
19710 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 sqlite3_vmprint
19720 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 f() routines wri
19730 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 te their.** resu
19740 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 lts into memory
19750 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
19760 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
19770 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 ..** The strings
19780 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
19790 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 se two routines
197a0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c should be.** rel
197b0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eased by [sqlite
197c0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 3_free()]. ^Bot
197d0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 h routines retur
197e0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
197f0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f ter if [sqlite3_
19800 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 malloc()] is una
19810 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 ble to allocate
19820 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 enough.** memory
19830 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 to hold the res
19840 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a ulting string..*
19850 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 *.** ^(The sqlit
19860 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f e3_snprintf() ro
19870 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 utine is similar
19880 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 to "snprintf()"
19890 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 from.** the sta
198a0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e ndard C library.
198b0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 The result is
198c0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 written into the
198d0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c .** buffer suppl
198e0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e ied as the secon
198f0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 d parameter whos
19900 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 e size is given
19910 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 by.** the first
19920 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 parameter. Note
19930 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f that the order o
19940 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 f the.** first t
19950 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 wo parameters is
19960 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 reversed from s
19970 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 nprintf().)^ Th
19980 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 is is an.** hist
19990 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 orical accident
199a0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 that cannot be f
199b0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 ixed without bre
199c0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 aking.** backwar
199d0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
199e0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 . ^(Note also t
199f0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 hat sqlite3_snpr
19a00 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e intf().** return
19a10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 s a pointer to i
19a20 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 ts buffer instea
19a30 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 d of the number
19a40 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 of.** characters
19a50 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 actually writte
19a60 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 n into the buffe
19a70 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 r.)^ We admit t
19a80 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 hat.** the numbe
19a90 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 r of characters
19aa0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 written would be
19ab0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 a more useful r
19ac0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 eturn.** value b
19ad0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 ut we cannot cha
19ae0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e nge the implemen
19af0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 tation of sqlite
19b00 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 3_snprintf().**
19b10 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 now without brea
19b20 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 king compatibili
19b30 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f ty..**.** ^As lo
19b40 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 ng as the buffer
19b50 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 size is greater
19b60 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 than zero, sqli
19b70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a te3_snprintf().*
19b80 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 * guarantees tha
19b90 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 t the buffer is
19ba0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d always zero-term
19bb0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 inated. ^The fi
19bc0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 rst.** parameter
19bd0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 "n" is the tota
19be0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 l size of the bu
19bf0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ffer, including
19c00 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 space for.** the
19c10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
19c20 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 . So the longes
19c30 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 t string that ca
19c40 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a n be completely.
19c50 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 ** written will
19c60 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 be n-1 character
19c70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
19c80 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 lite3_vsnprintf(
19c90 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 ) routine is a v
19ca0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f arargs version o
19cb0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e f sqlite3_snprin
19cc0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tf()..**.** Thes
19cd0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 e routines all i
19ce0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 mplement some ad
19cf0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 ditional formatt
19d00 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 ing.** options t
19d10 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 hat are useful f
19d20 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 or constructing
19d30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
19d40 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 ** All of the us
19d50 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 ual printf() for
19d60 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 matting options
19d70 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 apply. In addit
19d80 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 ion, there.** is
19d90 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c are "%q", "%Q",
19da0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
19db0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 s..**.** ^(The %
19dc0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c q option works l
19dd0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 ike %s in that i
19de0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 t substitutes a
19df0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a nul-terminated.*
19e00 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 * string from th
19e10 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e e argument list.
19e20 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f But %q also do
19e30 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 ubles every '\''
19e40 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 character..** %
19e50 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f q is designed fo
19e60 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 r use inside a s
19e70 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e tring literal.)^
19e80 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 By doubling ea
19e90 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 ch '\''.** chara
19ea0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 cter it escapes
19eb0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 that character a
19ec0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 nd allows it to
19ed0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f be inserted into
19ee0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a .** the string..
19ef0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c **.** For exampl
19f00 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 e, assume the st
19f10 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 ring variable zT
19f20 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 ext contains tex
19f30 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
19f40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
19f50 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
19f60 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 zText = "It's a
19f70 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 happy day!";.**
19f80 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
19f90 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 te>.**.** One ca
19fa0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 n use this text
19fb0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
19fc0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ent as follows:.
19fd0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
19fe0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
19ff0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
1a000 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
1a010 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
1a020 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 ES('%q')", zText
1a030 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
1a040 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
1a050 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
1a060 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
1a070 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1a080 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 quote>.**.** Bec
1a090 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d ause the %q form
1a0a0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 at string is use
1a0b0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 d, the '\'' char
1a0c0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a acter in zText.*
1a0d0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 * is escaped and
1a0e0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 the SQL generat
1a0f0 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 ed is as follows
1a100 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1a110 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e ote><pre>.** IN
1a120 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 SERT INTO table1
1a130 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 VALUES('It''s a
1a140 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a happy day!').**
1a150 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1a160 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ote>.**.** This
1a170 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 is correct. Had
1a180 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 we used %s inst
1a190 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 ead of %q, the g
1a1a0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 enerated SQL.**
1a1b0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 would have looke
1a1c0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a d like this:.**.
1a1d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1a1e0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
1a1f0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
1a200 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 ES('It's a happy
1a210 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 day!');.** </pr
1a220 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1a230 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e **.** This secon
1a240 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 d example is an
1a250 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 SQL syntax error
1a260 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 . As a general
1a270 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a rule you should.
1a280 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 ** always use %q
1a290 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 instead of %s w
1a2a0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 hen inserting te
1a2b0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 xt into a string
1a2c0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 literal..**.**
1a2d0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 ^(The %Q option
1a2e0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 works like %q ex
1a2f0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 cept it also add
1a300 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 s single quotes
1a310 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 around.** the ou
1a320 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 tside of the tot
1a330 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 al string. Addi
1a340 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 tionally, if the
1a350 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 parameter in th
1a360 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 e.** argument li
1a370 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 st is a NULL poi
1a380 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 nter, %Q substit
1a390 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e utes the text "N
1a3a0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a ULL" (without.**
1a3b0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e single quotes).
1a3c0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d )^ So, for exam
1a3d0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 ple, one could s
1a3e0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ay:.**.** <block
1a3f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1a400 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c char *zSQL = sql
1a410 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
1a420 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 SERT INTO table
1a430 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 VALUES(%Q)", zTe
1a440 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
1a450 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
1a460 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
1a470 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
1a480 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1a490 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1a4a0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 he code above wi
1a4b0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 ll render a corr
1a4c0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ect SQL statemen
1a4d0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a t in the zSQL.**
1a4e0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 variable even i
1a4f0 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 f the zText vari
1a500 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 able is a NULL p
1a510 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ointer..**.** ^(
1a520 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 The "%z" formatt
1a530 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 ing option works
1a540 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 like "%s" but w
1a550 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 ith the.** addit
1a560 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 ion that after t
1a570 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 he string has be
1a580 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 en read and copi
1a590 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 ed into.** the r
1a5a0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f esult, [sqlite3_
1a5b0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 free()] is calle
1a5c0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 d on the input s
1a5d0 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 tring.)^.*/.SQLI
1a5e0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c TE_API char *sql
1a5f0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e ite3_mprintf(con
1a600 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 st char*,...);.S
1a610 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a QLITE_API char *
1a620 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
1a630 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 (const char*, va
1a640 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 _list);.SQLITE_A
1a650 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 PI char *sqlite3
1a660 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
1a670 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1a680 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ...);.SQLITE_AP
1a690 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
1a6a0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 vsnprintf(int,ch
1a6b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1a6c0 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a va_list);../*.*
1a6d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
1a6e0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 ry Allocation Su
1a6f0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 bsystem.**.** Th
1a700 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 e SQLite core us
1a710 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 es these three r
1a720 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 outines for all
1a730 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e of its own.** in
1a740 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c ternal memory al
1a750 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 location needs.
1a760 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 "Core" in the pr
1a770 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a evious sentence.
1a780 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c ** does not incl
1a790 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 ude operating-sy
1a7a0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 stem specific VF
1a7b0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
1a7c0 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 . The.** Window
1a7d0 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 s VFS uses nativ
1a7e0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 e malloc() and f
1a7f0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f ree() for some o
1a800 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a perations..**.**
1a810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 ^The sqlite3_ma
1a820 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 lloc() routine r
1a830 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1a840 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f to a block.** o
1a850 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 f memory at leas
1a860 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e t N bytes in len
1a870 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 gth, where N is
1a880 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a the parameter..*
1a890 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 * ^If sqlite3_ma
1a8a0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 lloc() is unable
1a8b0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 to obtain suffi
1a8c0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 cient free.** me
1a8d0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 mory, it returns
1a8e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1a8f0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 ^If the parame
1a900 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 ter N to.** sqli
1a910 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 te3_malloc() is
1a920 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 zero or negative
1a930 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 then sqlite3_ma
1a940 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a lloc() returns.*
1a950 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 * a NULL pointer
1a960 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 ..**.** ^Calling
1a970 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 sqlite3_free()
1a980 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 with a pointer p
1a990 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e reviously return
1a9a0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 ed.** by sqlite3
1a9b0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
1a9c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 ite3_realloc() r
1a9d0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d eleases that mem
1a9e0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 ory so.** that i
1a9f0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 t might be reuse
1aa00 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 d. ^The sqlite3
1aa10 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 _free() routine
1aa20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 is.** a no-op if
1aa30 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
1aa40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1aa50 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 Passing a NULL
1aa60 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 pointer.** to sq
1aa70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 lite3_free() is
1aa80 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 harmless. After
1aa90 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 being freed, me
1aaa0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e mory.** should n
1aab0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e either be read n
1aac0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 or written. Eve
1aad0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f n reading previo
1aae0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 usly freed.** me
1aaf0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c mory might resul
1ab00 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 t in a segmentat
1ab10 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 ion fault or oth
1ab20 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e er severe error.
1ab30 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 .** Memory corru
1ab40 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 ption, a segment
1ab50 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 ation fault, or
1ab60 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 other severe err
1ab70 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 or.** might resu
1ab80 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 lt if sqlite3_fr
1ab90 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 ee() is called w
1aba0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 ith a non-NULL p
1abb0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 ointer that.** w
1abc0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 as not obtained
1abd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c from sqlite3_mal
1abe0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 loc() or sqlite3
1abf0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a _realloc()..**.*
1ac00 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f * ^(The sqlite3_
1ac10 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 realloc() interf
1ac20 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
1ac30 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
1ac40 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
1ac50 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 ion to be at lea
1ac60 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 st N bytes, wher
1ac70 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 e N is the.** se
1ac80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
1ac90 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f The memory allo
1aca0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 cation to be res
1acb0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 ized is the firs
1acc0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 t.** parameter.)
1acd0 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 ^ ^ If the first
1ace0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
1acf0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a lite3_realloc().
1ad00 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ** is a NULL poi
1ad10 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 nter then its be
1ad20 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 havior is identi
1ad30 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a cal to calling.*
1ad40 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
1ad50 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 (N) where N is t
1ad60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1ad70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
1ad80 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 ealloc()..** ^If
1ad90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
1ada0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
1adb0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 _realloc() is ze
1adc0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 ro or.** negativ
1add0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 e then the behav
1ade0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 ior is exactly t
1adf0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 he same as calli
1ae00 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 ng.** sqlite3_fr
1ae10 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 ee(P) where P is
1ae20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
1ae30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1ae40 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 realloc()..** ^s
1ae50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1ae60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1ae70 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 er to a memory a
1ae80 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
1ae90 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
1aea0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c in size or NULL
1aeb0 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d if sufficient m
1aec0 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c emory is unavail
1aed0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 able..** ^If M i
1aee0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 s the size of th
1aef0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1af00 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d on, then min(N,M
1af10 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 ) bytes.** of th
1af20 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
1af30 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e on are copied in
1af40 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 to the beginning
1af50 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 of buffer retur
1af60 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
1af70 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 3_realloc() and
1af80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1af90 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a tion is freed..*
1afa0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 * ^If sqlite3_re
1afb0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 alloc() returns
1afc0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 NULL, then the p
1afd0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a rior allocation.
1afe0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e ** is not freed.
1aff0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f .**.** ^The memo
1b000 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ry returned by s
1b010 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1b020 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c and sqlite3_real
1b030 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 loc().** is alwa
1b040 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 ys aligned to at
1b050 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 least an 8 byte
1b060 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f boundary, or to
1b070 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 a.** 4 byte bou
1b080 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 ndary if the [SQ
1b090 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 LITE_4_BYTE_ALIG
1b0a0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 NED_MALLOC] comp
1b0b0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
1b0c0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
1b0d0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 * In SQLite vers
1b0e0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e ion 3.5.0 and 3.
1b0f0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 5.1, it was poss
1b100 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a ible to define.*
1b110 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 * the SQLITE_OMI
1b120 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 T_MEMORY_ALLOCAT
1b130 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 ION which would
1b140 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d cause the built-
1b150 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 in.** implementa
1b160 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f tion of these ro
1b170 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 utines to be omi
1b180 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 tted. That capa
1b190 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 bility.** is no
1b1a0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e longer provided.
1b1b0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 Only built-in
1b1c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
1b1d0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a s can be used..*
1b1e0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 *.** Prior to SQ
1b1f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 Lite version 3.7
1b200 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 .10, the Windows
1b210 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 OS interface la
1b220 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 yer called.** th
1b230 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
1b240 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 ) and free() dir
1b250 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 ectly when conve
1b260 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d rting.** filenam
1b270 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 es between the U
1b280 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 TF-8 encoding us
1b290 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 ed by SQLite.**
1b2a0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c and whatever fil
1b2b0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 ename encoding i
1b2c0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 s used by the pa
1b2d0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 rticular Windows
1b2e0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e .** installation
1b2f0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 . Memory alloca
1b300 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 tion errors were
1b310 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a detected, but.*
1b320 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f * they were repo
1b330 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 rted back as [SQ
1b340 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f LITE_CANTOPEN] o
1b350 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 r.** [SQLITE_IOE
1b360 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 RR] rather than
1b370 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a [SQLITE_NOMEM]..
1b380 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 **.** The pointe
1b390 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b r arguments to [
1b3a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1b3b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
1b3c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 lloc()].** must
1b3d0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f be either NULL o
1b3e0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 r else pointers
1b3f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 obtained from a
1b400 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 prior.** invocat
1b410 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
1b420 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 malloc()] or [sq
1b430 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
1b440 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f that have.** no
1b450 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 t yet been relea
1b460 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 sed..**.** The a
1b470 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
1b480 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 not read or writ
1b490 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a e any part of.**
1b4a0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f a block of memo
1b4b0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 ry after it has
1b4c0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 been released us
1b4d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
1b4e0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 free()] or [sqli
1b4f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a te3_realloc()]..
1b500 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
1b510 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
1b520 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f oc(int);.SQLITE_
1b530 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
1b540 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 3_realloc(void*,
1b550 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
1b560 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 I void sqlite3_f
1b570 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a ree(void*);../*.
1b580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d ** CAPI3REF: Mem
1b590 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 ory Allocator St
1b5a0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 atistics.**.** S
1b5b0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 QLite provides t
1b5c0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 hese two interfa
1b5d0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e ces for reportin
1b5e0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a g on the status.
1b5f0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ** of the [sqlit
1b600 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 e3_malloc()], [s
1b610 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 qlite3_free()],
1b620 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 and [sqlite3_rea
1b630 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 lloc()].** routi
1b640 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 nes, which form
1b650 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d the built-in mem
1b660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
1b670 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 ubsystem..**.**
1b680 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 ^The [sqlite3_me
1b690 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 mory_used()] rou
1b6a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
1b6b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
1b6c0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 .** of memory cu
1b6d0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 rrently outstand
1b6e0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 ing (malloced bu
1b6f0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a t not freed)..**
1b700 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
1b710 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1b720 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 )] routine retur
1b730 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a ns the maximum.*
1b740 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 * value of [sqli
1b750 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
1b760 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 )] since the hig
1b770 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 h-water mark.**
1b780 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 was last reset.
1b790 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 ^The values ret
1b7a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 urned by [sqlite
1b7b0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
1b7c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
1b7d0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1b7e0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 r()] include any
1b7f0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 overhead.** add
1b800 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 ed by SQLite in
1b810 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 its implementati
1b820 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d on of [sqlite3_m
1b830 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 alloc()],.** but
1b840 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 not overhead ad
1b850 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 ded by the any u
1b860 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d nderlying system
1b870 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 library.** rout
1b880 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 ines that [sqlit
1b890 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 e3_malloc()] may
1b8a0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 call..**.** ^Th
1b8b0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 e memory high-wa
1b8c0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 ter mark is rese
1b8d0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 t to the current
1b8e0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 value of.** [sq
1b8f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
1b900 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 d()] if and only
1b910 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
1b920 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 r to.** [sqlite3
1b930 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
1b940 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e r()] is true. ^
1b950 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e The value return
1b960 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 ed.** by [sqlite
1b970 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
1b980 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 er(1)] is the hi
1b990 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
1b9a0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 prior to the re
1b9b0 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 set..*/.SQLITE_A
1b9c0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
1b9d0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f sqlite3_memory_
1b9e0 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 used(void);.SQLI
1b9f0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
1ba00 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
1ba10 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e ory_highwater(in
1ba20 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f t resetFlag);../
1ba30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
1ba40 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d seudo-Random Num
1ba50 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a ber Generator.**
1ba60 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 .** SQLite conta
1ba70 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 ins a high-quali
1ba80 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d ty pseudo-random
1ba90 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f number generato
1baa0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f r (PRNG) used to
1bab0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f .** select rando
1bac0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 m [ROWID | ROWID
1bad0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e s] when insertin
1bae0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e g new records in
1baf0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a to a table that.
1bb00 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 ** already uses
1bb10 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 the largest poss
1bb20 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 ible [ROWID]. T
1bb30 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 he PRNG is also
1bb40 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 used for.** the
1bb50 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 build-in random(
1bb60 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 ) and randomblob
1bb70 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 () SQL functions
1bb80 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 . This interfac
1bb90 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c e allows.** appl
1bba0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 ications to acce
1bbb0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 ss the same PRNG
1bbc0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f for other purpo
1bbd0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 ses..**.** ^A ca
1bbe0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
1bbf0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 ne stores N byte
1bc00 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 s of randomness
1bc10 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a into buffer P..*
1bc20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
1bc30 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e time this routin
1bc40 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 e is invoked (ei
1bc50 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 ther internally
1bc60 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 or by.** the app
1bc70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 lication) the PR
1bc80 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 NG is seeded usi
1bc90 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 ng randomness ob
1bca0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 tained.** from t
1bcb0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d he xRandomness m
1bcc0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 ethod of the def
1bcd0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
1bce0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f s] object..** ^O
1bcf0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 n all subsequent
1bd00 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 invocations, th
1bd10 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e e pseudo-randomn
1bd20 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 ess is generated
1bd30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 .** internally a
1bd40 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 nd without recou
1bd50 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 rse to the [sqli
1bd60 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d te3_vfs] xRandom
1bd70 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a ness.** method..
1bd80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
1bd90 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f id sqlite3_rando
1bda0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 mness(int N, voi
1bdb0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d *P);../*.** CA
1bdc0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d PI3REF: Compile-
1bdd0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 Time Authorizati
1bde0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a on Callbacks.**.
1bdf0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
1be00 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 registers an au
1be10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1be20 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 k with a particu
1be30 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 lar.** [database
1be40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 connection], su
1be50 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 pplied in the fi
1be60 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a rst argument..**
1be70 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 ^The authorizer
1be80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
1be90 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 oked as SQL stat
1bea0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 ements are being
1beb0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 compiled.** by
1bec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1bed0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
1bee0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 nts [sqlite3_pre
1bef0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b pare_v2()],.** [
1bf00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1bf10 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 6()] and [sqlite
1bf20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
1bf30 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a ]. ^At various.
1bf40 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 ** points during
1bf50 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e the compilation
1bf60 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 process, as log
1bf70 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 ic is being crea
1bf80 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 ted.** to perfor
1bf90 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e m various action
1bfa0 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 s, the authorize
1bfb0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
1bfc0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 voked to.** see
1bfd0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 if those actions
1bfe0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e are allowed. ^
1bff0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
1c000 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a allback should.*
1c010 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
1c020 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 _OK] to allow th
1c030 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 e action, [SQLIT
1c040 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 E_IGNORE] to dis
1c050 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 allow the.** spe
1c060 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 cific action but
1c070 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 allow the SQL s
1c080 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 tatement to cont
1c090 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f inue to be.** co
1c0a0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 mpiled, or [SQLI
1c0b0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 TE_DENY] to caus
1c0c0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c e the entire SQL
1c0d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
1c0e0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 .** rejected wit
1c0f0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 h an error. ^If
1c100 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1c110 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1c120 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 .** any value ot
1c130 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
1c140 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 _IGNORE], [SQLIT
1c150 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 E_OK], or [SQLIT
1c160 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 E_DENY].** then
1c170 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 the [sqlite3_pre
1c180 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
1c190 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
1c1a0 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 at triggered.**
1c1b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 the authorizer w
1c1c0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
1c1d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
1c1e0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 **.** When the c
1c1f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1c200 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 [SQLITE_OK], tha
1c210 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 t means the oper
1c220 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 ation.** request
1c230 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e ed is ok. ^When
1c240 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1c250 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 turns [SQLITE_DE
1c260 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c NY], the.** [sql
1c270 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
1c280 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
1c290 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
1c2a0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 ered the.** auth
1c2b0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
1c2c0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
1c2d0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e essage explainin
1c2e0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 g that.** access
1c2f0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a is denied. .**.
1c300 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 ** ^The first pa
1c310 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 rameter to the a
1c320 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1c330 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
1c340 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 the third.** par
1c350 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
1c360 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1c370 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 izer() interface
1c380 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
1c390 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 rameter.** to th
1c3a0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e e callback is an
1c3b0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 integer [SQLITE
1c3c0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 _COPY | action c
1c3d0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 ode] that specif
1c3e0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 ies.** the parti
1c3f0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 cular action to
1c400 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e be authorized. ^
1c410 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 The third throug
1c420 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 h sixth paramete
1c430 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c rs.** to the cal
1c440 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 lback are zero-t
1c450 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
1c460 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 s that contain a
1c470 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 dditional.** det
1c480 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
1c490 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
1c4a0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 orized..**.** ^I
1c4b0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
1c4c0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 e is [SQLITE_REA
1c4d0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 D].** and the ca
1c4e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b llback returns [
1c4f0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
1c500 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 hen the.** [prep
1c510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1c520 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e statement is con
1c530 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 structed to subs
1c540 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c titute.** a NULL
1c550 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 value in place
1c560 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c of the table col
1c570 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 umn that would h
1c580 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 ave.** been read
1c590 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 if [SQLITE_OK]
1c5a0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 had been returne
1c5b0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f d. The [SQLITE_
1c5c0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 IGNORE].** retur
1c5d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
1c5e0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 deny an untrust
1c5f0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 ed user access t
1c600 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 o individual.**
1c610 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 columns of a tab
1c620 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 le..** ^If the a
1c630 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 ction code is [S
1c640 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e QLITE_DELETE] an
1c650 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 d the callback r
1c660 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 eturns.** [SQLIT
1c670 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
1c680 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 he [DELETE] oper
1c690 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 ation proceeds b
1c6a0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 ut the.** [trunc
1c6b0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e ate optimization
1c6c0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e ] is disabled an
1c6d0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 d all rows are d
1c6e0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 eleted individua
1c6f0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 lly..**.** An au
1c700 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 thorizer is used
1c710 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 when [sqlite3_p
1c720 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 repare | prepari
1c730 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ng].** SQL state
1c740 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e ments from an un
1c750 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 trusted source,
1c760 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 to ensure that t
1c770 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1c780 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 s.** do not try
1c790 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 to access data t
1c7a0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f hey are not allo
1c7b0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 wed to see, or t
1c7c0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a hat they do not.
1c7d0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 ** try to execut
1c7e0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 e malicious stat
1c7f0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 ements that dama
1c800 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e ge the database.
1c810 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 For.** example
1c820 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
1c830 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 may allow a use
1c840 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 r to enter arbit
1c850 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 rary.** SQL quer
1c860 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 ies for evaluati
1c870 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 on by a database
1c880 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 . But the appli
1c890 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e cation does.** n
1c8a0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 ot want the user
1c8b0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d to be able to m
1c8c0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 ake arbitrary ch
1c8d0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 anges to the.**
1c8e0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 database. An au
1c8f0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 thorizer could t
1c900 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c hen be put in pl
1c910 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a ace while the.**
1c920 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 user-entered SQ
1c930 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 L is being [sqli
1c940 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
1c950 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 epared] that.**
1c960 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 disallows everyt
1c970 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c hing except [SEL
1c980 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e ECT] statements.
1c990 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
1c9a0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f ons that need to
1c9b0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f process SQL fro
1c9c0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 m untrusted sour
1c9d0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 ces.** might als
1c9e0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 o consider lower
1c9f0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d ing resource lim
1ca00 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 its using [sqlit
1ca10 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 e3_limit()].** a
1ca20 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 nd limiting data
1ca30 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 base size using
1ca40 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f the [max_page_co
1ca50 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a unt] [PRAGMA].**
1ca60 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 in addition to
1ca70 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 using an authori
1ca80 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c zer..**.** ^(Onl
1ca90 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f y a single autho
1caa0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 rizer can be in
1cab0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 place on a datab
1cac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
1cad0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 * at a time. Ea
1cae0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 ch call to sqlit
1caf0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 e3_set_authorize
1cb00 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a r overrides the.
1cb10 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c ** previous call
1cb20 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 .)^ ^Disable th
1cb30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 e authorizer by
1cb40 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c installing a NUL
1cb50 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 L callback..** T
1cb60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 he authorizer is
1cb70 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
1cb80 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ault..**.** The
1cb90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1cba0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 ack must not do
1cbb0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 anything that wi
1cbc0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 ll modify.** the
1cbd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1cbe0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1cbf0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 d the authorizer
1cc00 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f callback..** No
1cc10 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 te that [sqlite3
1cc20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 _prepare_v2()] a
1cc30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 nd [sqlite3_step
1cc40 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 ()] both modify
1cc50 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 their.** databas
1cc60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f e connections fo
1cc70 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 r the meaning of
1cc80 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 "modify" in thi
1cc90 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a s paragraph..**.
1cca0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 ** ^When [sqlite
1ccb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1ccc0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 is used to prepa
1ccd0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 re a statement,
1cce0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 the.** statement
1ccf0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 might be re-pre
1cd00 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 pared during [sq
1cd10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 lite3_step()] du
1cd20 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d e to a .** schem
1cd30 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 a change. Hence
1cd40 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
1cd50 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 n should ensure
1cd60 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 that the.** corr
1cd70 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 ect authorizer c
1cd80 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 allback remains
1cd90 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 in place during
1cda0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
1cdb0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 p()]..**.** ^Not
1cdc0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f e that the autho
1cdd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
1cde0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 s invoked only d
1cdf0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 uring.** [sqlite
1ce00 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 3_prepare()] or
1ce10 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 its variants. A
1ce20 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 uthorization is
1ce30 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 not.** performed
1ce40 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e during statemen
1ce50 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 t evaluation in
1ce60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1ce70 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 , unless.** as s
1ce80 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 tated in the pre
1ce90 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c vious paragraph,
1cea0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
1ceb0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 invokes.** sqlit
1cec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
1ced0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 to reprepare a s
1cee0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 tatement after a
1cef0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a schema change..
1cf00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1cf10 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 t sqlite3_set_au
1cf20 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 thorizer(. sqli
1cf30 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 te3*,. int (*xA
1cf40 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 uth)(void*,int,c
1cf50 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 onst char*,const
1cf60 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
1cf70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c r*,const char*),
1cf80 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 . void *pUserDa
1cf90 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ta.);../*.** CAP
1cfa0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 I3REF: Authorize
1cfb0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a r Return Codes.*
1cfc0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 *.** The [sqlite
1cfd0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
1cfe0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 | authorizer ca
1cff0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d llback function]
1d000 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 must.** return
1d010 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f either [SQLITE_O
1d020 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 K] or one of the
1d030 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 se two constants
1d040 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 in order.** to
1d050 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 signal SQLite wh
1d060 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
1d070 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 action is permi
1d080 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a tted. See the.*
1d090 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 * [sqlite3_set_a
1d0a0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 uthorizer | auth
1d0b0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 orizer documenta
1d0c0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 tion] for additi
1d0d0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 onal.** informat
1d0e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 ion..**.** Note
1d0f0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f that SQLITE_IGNO
1d100 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 RE is also used
1d110 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c as a [SQLITE_ROL
1d120 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 LBACK | return c
1d130 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 ode].** from the
1d140 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f [sqlite3_vtab_o
1d150 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e n_conflict()] in
1d160 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 terface..*/.#def
1d170 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 ine SQLITE_DENY
1d180 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 1 /* Abort t
1d190 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1d1a0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a with an error *
1d1b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1d1c0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 _IGNORE 2 /* D
1d1d0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 on't allow acces
1d1e0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e s, but don't gen
1d1f0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a erate an error *
1d200 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
1d210 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 F: Authorizer Ac
1d220 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
1d230 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1d240 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
1d250 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
1d260 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
1d270 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
1d280 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
1d290 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
1d2a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
1d2b0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
1d2c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1d2d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1d2e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
1d2f0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
1d300 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
1d310 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
1d320 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
1d330 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
1d340 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
1d350 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
1d360 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
1d370 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
1d380 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
1d390 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
1d3a0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
1d3b0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
1d3c0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
1d3d0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
1d3e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
1d3f0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
1d400 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
1d410 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
1d420 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
1d430 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
1d440 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
1d450 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
1d460 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1d470 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 eter. ^(The 5th
1d480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1d490 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
1d4a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
1d4b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
1d4c0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 base ("main", "t
1d4d0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 emp",.** etc.) i
1d4e0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 f applicable.)^
1d4f0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 ^The 6th parame
1d500 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
1d510 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a rizer callback.*
1d520 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
1d530 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
1d540 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
1d550 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
1d560 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ble for.** the a
1d570 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
1d580 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
1d590 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
1d5a0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a directly from.**
1d5b0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 top-level SQL c
1d5c0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ode..*/./*******
1d5d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1d5e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1d5f0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
1d600 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
1d610 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
1d620 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
1d630 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
1d640 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
1d650 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1d660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1d670 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
1d680 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
1d690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1d6a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1d6b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1d6c0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1d6d0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
1d6e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
1d6f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1d700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1d710 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
1d720 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
1d730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1d740 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1d750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1d760 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
1d770 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
1d780 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
1d790 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1d7a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1d7b0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
1d7c0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
1d7d0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
1d7e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1d7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1d800 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
1d810 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
1d820 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
1d830 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1d840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1d850 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
1d860 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
1d870 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
1d880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1d890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1d8a0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
1d8b0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
1d8c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1d8d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1d8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1d8f0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
1d900 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
1d910 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
1d920 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1d930 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1d940 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
1d950 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
1d960 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1d970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1d980 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1d990 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
1d9a0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
1d9b0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1d9c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1d9d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1d9e0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
1d9f0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
1da00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1da10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1da20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
1da30 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
1da40 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
1da50 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
1da60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1da70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
1da80 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
1da90 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
1daa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1dab0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1dac0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
1dad0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
1dae0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1daf0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1db00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1db10 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
1db20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
1db30 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
1db40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1db50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1db60 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
1db70 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
1db80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1db90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1dba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1dbb0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
1dbc0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
1dbd0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
1dbe0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
1dbf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1dc00 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
1dc10 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
1dc20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1dc30 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
1dc40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1dc50 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
1dc60 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
1dc70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
1dc80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1dc90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1dca0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
1dcb0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
1dcc0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
1dcd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1dce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1dcf0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
1dd00 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
1dd10 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
1dd20 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
1dd30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
1dd40 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
1dd50 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
1dd60 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
1dd70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1dd80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1dd90 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
1dda0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
1ddb0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
1ddc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1ddd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
1dde0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
1ddf0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
1de00 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
1de10 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1de20 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
1de30 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
1de40 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
1de50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1de60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1de70 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
1de80 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
1de90 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
1dea0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1deb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1dec0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1ded0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
1dee0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
1def0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
1df00 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
1df10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
1df20 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
1df30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1df40 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
1df50 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
1df60 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
1df70 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
1df80 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
1df90 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
1dfa0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
1dfb0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
1dfc0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
1dfd0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
1dfe0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
1dff0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
1e000 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
1e010 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
1e020 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
1e030 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d */../*.** CAPI
1e040 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 3REF: Tracing An
1e050 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 d Profiling Func
1e060 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
1e070 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 e routines regis
1e080 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e ter callback fun
1e090 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 ctions that can
1e0a0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 be used for.** t
1e0b0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 racing and profi
1e0c0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 ling the executi
1e0d0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d on of SQL statem
1e0e0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
1e0f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1e100 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 on registered by
1e110 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
1e120 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a is invoked at.*
1e130 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 * various times
1e140 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 when an SQL stat
1e150 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 ement is being r
1e160 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 un by [sqlite3_s
1e170 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 tep()]..** ^The
1e180 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
1e190 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
1e1a0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 ked with a UTF-8
1e1b0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 rendering of th
1e1c0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 e.** SQL stateme
1e1d0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 nt text as the s
1e1e0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 tatement first b
1e1f0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e egins executing.
1e200 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c .** ^(Additional
1e210 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
1e220 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 callbacks might
1e230 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 occur.** as eac
1e240 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 h triggered subp
1e250 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 rogram is entere
1e260 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b d. The callback
1e270 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a s for triggers.*
1e280 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d * contain a UTF-
1e290 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 8 SQL comment th
1e2a0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 at identifies th
1e2b0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a e trigger.)^.**.
1e2c0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b ** ^The callback
1e2d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 function regist
1e2e0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ered by sqlite3_
1e2f0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 profile() is inv
1e300 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 oked.** as each
1e310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 SQL statement fi
1e320 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 nishes. ^The pr
1e330 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 ofile callback c
1e340 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f ontains.** the o
1e350 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e riginal statemen
1e360 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 t text and an es
1e370 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 timate of wall-c
1e380 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 lock time.** of
1e390 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 how long that st
1e3a0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
1e3b0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 run. ^The profi
1e3c0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 le callback.** t
1e3d0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 ime is in units
1e3e0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 of nanoseconds,
1e3f0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 however the curr
1e400 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ent implementati
1e410 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 on.** is only ca
1e420 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 pable of millise
1e430 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 cond resolution
1e440 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 so the six least
1e450 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 significant.**
1e460 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 digits in the ti
1e470 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 me are meaningle
1e480 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ss. Future vers
1e490 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a ions of SQLite.*
1e4a0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 * might provide
1e4b0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 greater resoluti
1e4c0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c on on the profil
1e4d0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 er callback. Th
1e4e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f e.** sqlite3_pro
1e4f0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 file() function
1e500 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 is considered ex
1e510 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 perimental and i
1e520 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 s.** subject to
1e530 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 change in future
1e540 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
1e550 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ite..*/.SQLITE_A
1e560 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 PI void *sqlite3
1e570 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
1e580 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
1e590 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
1e5a0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
1e5b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 E_API SQLITE_EXP
1e5c0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a ERIMENTAL void *
1e5d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
1e5e0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 sqlite3*,. voi
1e5f0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 d(*xProfile)(voi
1e600 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 d*,const char*,s
1e610 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 qlite3_uint64),
1e620 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
1e630 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 API3REF: Query P
1e640 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b rogress Callback
1e650 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
1e660 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
1e670 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 ndler(D,N,X,P) i
1e680 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 nterface causes
1e690 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 the callback.**
1e6a0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 function X to be
1e6b0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 invoked periodi
1e6c0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e cally during lon
1e6d0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 g running calls
1e6e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 to.** [sqlite3_e
1e6f0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 xec()], [sqlite3
1e700 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 _step()] and [sq
1e710 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1e720 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 )] for.** databa
1e730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e se connection D.
1e740 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 An example use
1e750 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 for this.** int
1e760 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 erface is to kee
1e770 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 p a GUI updated
1e780 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 during a large q
1e790 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 uery..**.** ^The
1e7a0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 parameter P is
1e7b0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 passed through a
1e7c0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d s the only param
1e7d0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 eter to the .**
1e7e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1e7f0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d n X. ^The param
1e800 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 eter N is the nu
1e810 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 mber of .** [vir
1e820 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 tual machine ins
1e830 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 tructions] that
1e840 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 are evaluated be
1e850 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 tween successive
1e860 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 .** invocations
1e870 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 of the callback
1e880 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 X..**.** ^Only a
1e890 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 single progress
1e8a0 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 handler may be
1e8b0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 defined at one t
1e8c0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 ime per.** [data
1e8d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1e8e0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 ; setting a new
1e8f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 progress handler
1e900 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 cancels the.**
1e910 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 old one. ^Setti
1e920 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 ng parameter X t
1e930 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 o NULL disables
1e940 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e the progress han
1e950 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 dler..** ^The pr
1e960 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 ogress handler i
1e970 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 s also disabled
1e980 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 by setting N to
1e990 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 a value less.**
1e9a0 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 than 1..**.** ^I
1e9b0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 f the progress c
1e9c0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1e9d0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 non-zero, the op
1e9e0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e eration is.** in
1e9f0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 terrupted. This
1ea00 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 feature can be
1ea10 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
1ea20 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 t a.** "Cancel"
1ea30 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 button on a GUI
1ea40 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 progress dialog
1ea50 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 box..**.** The p
1ea60 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
1ea70 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f callback must no
1ea80 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
1ea90 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
1eaa0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
1eab0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
1eac0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 nvoked the progr
1ead0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 ess handler..**
1eae0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
1eaf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1eb00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
1eb10 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
1eb20 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
1eb30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
1eb40 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
1eb50 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
1eb60 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
1eb70 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 *.*/.SQLITE_API
1eb80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f void sqlite3_pro
1eb90 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 gress_handler(sq
1eba0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 lite3*, int, int
1ebb0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
1ebc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
1ebd0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e REF: Opening A N
1ebe0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e ew Database Conn
1ebf0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ection.**.** ^Th
1ec00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 ese routines ope
1ec10 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 n an SQLite data
1ec20 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 base file as spe
1ec30 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a cified by the .*
1ec40 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d * filename argum
1ec50 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 ent. ^The filena
1ec60 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 me argument is i
1ec70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 nterpreted as UT
1ec80 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 F-8 for.** sqlit
1ec90 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 e3_open() and sq
1eca0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
1ecb0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e and as UTF-16 in
1ecc0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
1ecd0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 .** order for sq
1ece0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 lite3_open16().
1ecf0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f ^(A [database co
1ed00 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 nnection] handle
1ed10 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 is usually.** r
1ed20 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 eturned in *ppDb
1ed30 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 , even if an err
1ed40 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 or occurs. The
1ed50 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 only exception i
1ed60 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c s that.** if SQL
1ed70 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f ite is unable to
1ed80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 allocate memory
1ed90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 to hold the [sq
1eda0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a lite3] object,.*
1edb0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 * a NULL will be
1edc0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 written into *p
1edd0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 pDb instead of a
1ede0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
1edf0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a [sqlite3].** obj
1ee00 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 ect.)^ ^(If the
1ee10 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1ee20 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 ed (and/or creat
1ee30 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 ed) successfully
1ee40 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 , then.** [SQLIT
1ee50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 E_OK] is returne
1ee60 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e d. Otherwise an
1ee70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 [error code] is
1ee80 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 returned.)^ ^Th
1ee90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 e.** [sqlite3_er
1eea0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 rmsg()] or [sqli
1eeb0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 te3_errmsg16()]
1eec0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 routines can be
1eed0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a used to obtain.*
1eee0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e * an English lan
1eef0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f guage descriptio
1ef00 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 n of the error f
1ef10 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 ollowing a failu
1ef20 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 re of any.** of
1ef30 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e the sqlite3_open
1ef40 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a () routines..**.
1ef50 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
1ef60 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 encoding for the
1ef70 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 database will b
1ef80 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 e UTF-8 if.** sq
1ef90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
1efa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
1efb0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a ) is called and.
1efc0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 ** UTF-16 in the
1efd0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
1efe0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 er if sqlite3_op
1eff0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a en16() is used..
1f000 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 **.** Whether or
1f010 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 not an error oc
1f020 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 curs when it is
1f030 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 opened, resource
1f040 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 s.** associated
1f050 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
1f060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
1f070 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 andle should be
1f080 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 released by.** p
1f090 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
1f0a0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 lite3_close()] w
1f0b0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e hen it is no lon
1f0c0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a ger required..**
1f0d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
1f0e0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 open_v2() interf
1f0f0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 ace works like s
1f100 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a qlite3_open().**
1f110 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
1f120 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 accepts two addi
1f130 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 tional parameter
1f140 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c s for additional
1f150 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 control.** over
1f160 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 the new databas
1f170 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
1f180 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d (The flags param
1f190 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 eter to.** sqlit
1f1a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e e3_open_v2() can
1f1b0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 take one of.**
1f1c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 the following th
1f1d0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 ree values, opti
1f1e0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
1f1f0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
1f200 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
1f210 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e X], [SQLITE_OPEN
1f220 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 _FULLMUTEX], [SQ
1f230 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
1f240 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 CACHE],.** [SQLI
1f250 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
1f260 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 ACHE], and/or [S
1f270 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
1f280 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c flags:)^.**.** <
1f290 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 dl>.** ^(<dt>[SQ
1f2a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
1f2b0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LY]</dt>.** <dd>
1f2c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
1f2d0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f opened in read-o
1f2e0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 nly mode. If th
1f2f0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 e database does
1f300 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 not.** already e
1f310 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 xist, an error i
1f320 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
1f330 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b )^.**.** ^(<dt>[
1f340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
1f350 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c WRITE]</dt>.** <
1f360 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
1f370 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
1f380 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
1f390 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f g if possible, o
1f3a0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c r reading.** onl
1f3b0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 y if the file is
1f3c0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 write protected
1f3d0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e by the operatin
1f3e0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 g system. In ei
1f3f0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 ther.** case the
1f400 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 database must a
1f410 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 lready exist, ot
1f420 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 herwise an error
1f430 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
1f440 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
1f450 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
1f460 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
1f470 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c TE_OPEN_CREATE]<
1f480 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
1f490 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
1f4a0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
1f4b0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 nd writing, and
1f4c0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a is created if.**
1f4d0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 it does not alr
1f4e0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 eady exist. This
1f4f0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 is the behavior
1f500 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 that is always
1f510 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 used for.** sqli
1f520 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
1f530 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
1f540 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e </dd>)^.** </dl>
1f550 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 .**.** If the 3r
1f560 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
1f570 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
1f580 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 is not one of t
1f590 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f he.** combinatio
1f5a0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f ns shown above o
1f5b0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
1f5c0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a ed with other.**
1f5d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
1f5e0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f ADONLY | SQLITE_
1f5f0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 OPEN_* bits].**
1f600 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
1f610 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
1f620 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 **.** ^If the [S
1f630 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
1f640 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c EX] flag is set,
1f650 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
1f660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
1f670 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 opens in the mu
1f680 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
1f690 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c ading mode] as l
1f6a0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c ong as the singl
1f6b0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 e-thread.** mode
1f6c0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 has not been se
1f6d0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d t at compile-tim
1f6e0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e e or start-time.
1f6f0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 ^If the.** [SQ
1f700 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
1f710 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
1f720 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
1f730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 se connection op
1f740 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 ens.** in the se
1f750 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
1f760 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 ing mode] unless
1f770 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 single-thread w
1f780 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 as.** previously
1f790 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d selected at com
1f7a0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 pile-time or sta
1f7b0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 rt-time..** ^The
1f7c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 [SQLITE_OPEN_SH
1f7d0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 AREDCACHE] flag
1f7e0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 causes the datab
1f7f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
1f800 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 o be.** eligible
1f810 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 to use [shared
1f820 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 cache mode], reg
1f830 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
1f840 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 er or not shared
1f850 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 .** cache is ena
1f860 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 bled using [sqli
1f870 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 te3_enable_share
1f880 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 d_cache()]. ^Th
1f890 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
1f8a0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 N_PRIVATECACHE]
1f8b0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 flag causes the
1f8c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f8d0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 ion to not.** pa
1f8e0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 rticipate in [sh
1f8f0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d ared cache mode]
1f900 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 even if it is e
1f910 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 nabled..**.** ^T
1f920 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
1f930 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
1f940 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 pen_v2() is the
1f950 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b name of the.** [
1f960 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
1f970 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 ect that defines
1f980 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
1f990 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
1f9a0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 that.** the new
1f9b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1f9c0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 ion should use.
1f9d0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
1f9e0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
1f9f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
1fa00 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 hen the default
1fa10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
1fa20 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a ject is used..**
1fa30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 .** ^If the file
1fa40 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 name is ":memory
1fa50 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 :", then a priva
1fa60 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e te, temporary in
1fa70 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
1fa80 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 .** is created f
1fa90 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f or the connectio
1faa0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d n. ^This in-mem
1fab0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c ory database wil
1fac0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a l vanish when.**
1fad0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1fae0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
1faf0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ed. Future vers
1fb00 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
1fb10 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 ight.** make use
1fb20 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 of additional s
1fb30 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 pecial filenames
1fb40 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 that begin with
1fb50 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 the ":" charact
1fb60 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 er..** It is rec
1fb70 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 ommended that wh
1fb80 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 en a database fi
1fb90 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 lename actually
1fba0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a does begin with.
1fbb0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 ** a ":" charact
1fbc0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 er you should pr
1fbd0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d efix the filenam
1fbe0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d e with a pathnam
1fbf0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f e such as.** "./
1fc00 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 " to avoid ambig
1fc10 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 uity..**.** ^If
1fc20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
1fc30 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
1fc40 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
1fc50 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e temporary.** on
1fc60 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 -disk database w
1fc70 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 ill be created.
1fc80 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 ^This private d
1fc90 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a atabase will be.
1fca0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
1fcb0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e deleted as soon
1fcc0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 as the database
1fcd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
1fce0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 losed..**.** [[U
1fcf0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 RI filenames in
1fd00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d sqlite3_open()]]
1fd10 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d <h3>URI Filenam
1fd20 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 es</h3>.**.** ^I
1fd30 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d f [URI filename]
1fd40 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
1fd50 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 is enabled, and
1fd60 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 the filename arg
1fd70 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 ument.** begins
1fd80 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 with "file:", th
1fd90 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 en the filename
1fda0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
1fdb0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a s a URI. ^URI.**
1fdc0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 filename interp
1fdd0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 retation is enab
1fde0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 led if the [SQLI
1fdf0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
1fe00 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 g is.** set in t
1fe10 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
1fe20 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
1fe30 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 en_v2(), or if i
1fe40 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e t has.** been en
1fe50 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 abled globally u
1fe60 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
1fe70 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 _CONFIG_URI] opt
1fe80 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 ion with the.**
1fe90 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
1fea0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 )] method or by
1feb0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f the [SQLITE_USE_
1fec0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d URI] compile-tim
1fed0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 e option..** As
1fee0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f of SQLite versio
1fef0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c n 3.7.7, URI fil
1ff00 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
1ff10 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f tion is turned o
1ff20 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 ff.** by default
1ff30 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c , but future rel
1ff40 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 eases of SQLite
1ff50 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 might enable URI
1ff60 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 filename.** int
1ff70 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 erpretation by d
1ff80 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 efault. See "[U
1ff90 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 RI filenames]" f
1ffa0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
1ffb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
1ffc0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
1ffd0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 s are parsed acc
1ffe0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 ording to RFC 39
1fff0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 86. ^If the URI
20000 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 contains an.** a
20010 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 uthority, then i
20020 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 t must be either
20030 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
20040 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a or the string .
20050 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 ** "localhost".
20060 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 ^If the authorit
20070 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 y is not an empt
20080 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 y string or "loc
20090 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 alhost", an .**
200a0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
200b0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e d to the caller.
200c0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 ^The fragment c
200d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 omponent of a UR
200e0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e I, if .** presen
200f0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a t, is ignored..*
20100 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 *.** ^SQLite use
20110 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f s the path compo
20120 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 nent of the URI
20130 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 as the name of t
20140 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 he disk file.**
20150 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 which contains t
20160 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 he database. ^If
20170 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 the path begins
20180 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 with a '/' char
20190 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 acter, .** then
201a0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 it is interprete
201b0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 d as an absolute
201c0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 path. ^If the p
201d0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 ath does not beg
201e0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f in .** with a '/
201f0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 ' (meaning that
20200 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 the authority se
20210 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 ction is omitted
20220 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a from the URI).*
20230 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 * then the path
20240 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
20250 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 s a relative pat
20260 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f h. .** ^On windo
20270 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f ws, the first co
20280 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 mponent of an ab
20290 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 solute path .**
202a0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 is a drive speci
202b0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 fication (e.g. "
202c0 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f C:")..**.** [[co
202d0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 re URI query par
202e0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 ameters]].** The
202f0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
20300 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f of a URI may co
20310 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 ntain parameters
20320 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 that are interp
20330 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 reted.** either
20340 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 by SQLite itself
20350 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c , or by a [VFS |
20360 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c custom VFS impl
20370 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 ementation]..**
20380 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 SQLite interpret
20390 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 s the following
203a0 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 three query para
203b0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 meters:.**.** <u
203c0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e l>.** <li> <b>
203d0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 vfs</b>: ^The "v
203e0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 fs" parameter ma
203f0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 y be used to spe
20400 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 cify the name of
20410 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 .** a VFS ob
20420 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 ject that provid
20430 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
20440 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
20450 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a e that should.**
20460 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 be used to
20470 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
20480 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b ase file on disk
20490 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f . ^If this optio
204a0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 n is set to.**
204b0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 an empty stri
204c0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 ng the default V
204d0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 FS object is use
204e0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 d. ^Specifying a
204f0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 n unknown.**
20500 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 VFS is an error
20510 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 . ^If sqlite3_op
20520 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 en_v2() is used
20530 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 and the vfs opti
20540 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 on is.** pre
20550 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 sent, then the V
20560 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 FS specified by
20570 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 the option takes
20580 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 precedence over
20590 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 .** the valu
205a0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
205b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
205c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
205d0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c _v2()..**.** <
205e0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a li> <b>mode</b>:
205f0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 ^(The mode para
20600 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
20610 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c to either "ro",
20620 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 "rw",.** "r
20630 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 wc", or "memory"
20640 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 . Attempting to
20650 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 set it to any ot
20660 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 her value is.**
20670 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 an error)^.
20680 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 .** ^If "ro"
20690 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
206a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
206b0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
206c0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 ead-only .**
206d0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 access, just as
206e0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
206f0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 OPEN_READONLY] f
20700 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 lag had been set
20710 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 in the .**
20720 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
20730 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
20740 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 2(). ^If the mod
20750 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 e option is set
20760 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c to .** "rw",
20770 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
20780 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
20790 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 read-write (but
207a0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a not create) .**
207b0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 access, as
207c0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 if SQLITE_OPEN_R
207d0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f EADWRITE (but no
207e0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 t SQLITE_OPEN_CR
207f0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 EATE) had .**
20800 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c been set. ^Val
20810 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 ue "rwc" is equi
20820 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
20830 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 g both .** S
20840 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
20850 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f RITE and SQLITE_
20860 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 OPEN_CREATE. ^I
20870 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
20880 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 n is.** set
20890 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e to "memory" then
208a0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f a pure [in-memo
208b0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 ry database] tha
208c0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a t never reads.**
208d0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 or writes f
208e0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 rom disk is used
208f0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f . ^It is an erro
20900 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 r to specify a v
20910 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 alue for.**
20920 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 the mode paramet
20930 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 er that is less
20940 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e restrictive than
20950 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 that specified
20960 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c by.** the fl
20970 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 ags passed in th
20980 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
20990 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
209a0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 n_v2()..**.**
209b0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 <li> <b>cache</b
209c0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 >: ^The cache pa
209d0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
209e0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 et to either "sh
209f0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 ared" or.**
20a00 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 "private". ^Sett
20a10 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 ing it to "share
20a20 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 d" is equivalent
20a30 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a to setting the.
20a40 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
20a50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 EN_SHAREDCACHE b
20a60 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 it in the flags
20a70 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
20a80 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 to.** sqlite
20a90 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 3_open_v2(). ^Se
20aa0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 tting the cache
20ab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 parameter to "pr
20ac0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 ivate" is .**
20ad0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 equivalent to
20ae0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 setting the SQLI
20af0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
20b00 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 ACHE bit..**
20b10 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
20b20 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
20b30 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 nd the "cache" p
20b40 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 arameter is pres
20b50 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 ent in.** a
20b60 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 URI filename, it
20b70 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 s value override
20b80 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 s any behaviour
20b90 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 requested by set
20ba0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 ting.** SQLI
20bb0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
20bc0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f ACHE or SQLITE_O
20bd0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 PEN_SHAREDCACHE
20be0 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a flag..** </ul>.*
20bf0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 *.** ^Specifying
20c00 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 an unknown para
20c10 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 meter in the que
20c20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 ry component of
20c30 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a a URI is not an.
20c40 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 ** error. Futur
20c50 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
20c60 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 Lite might under
20c70 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c stand additional
20c80 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 query.** parame
20c90 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 ters. See "[que
20ca0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 ry parameters wi
20cb0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 th special meani
20cc0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 ng to SQLite]" f
20cd0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c or.** additional
20ce0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
20cf0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 .** [[URI filena
20d00 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 me examples]] <h
20d10 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 3>URI filename e
20d20 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a xamples</h3>.**.
20d30 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 ** <table border
20d40 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 ="1" align=cente
20d50 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e r cellpadding=5>
20d60 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 .** <tr><th> URI
20d70 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 filenames <th>
20d80 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c Results.** <tr><
20d90 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 td> file:data.db
20da0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
20db0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 Open the file
20dc0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
20dd0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
20de0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ory..** <tr><td>
20df0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
20e00 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 /data.db<br>.**
20e10 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
20e20 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
20e30 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 db <br> .**
20e40 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 file://loca
20e50 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f lhost/home/fred/
20e60 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 data.db <br> <td
20e70 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
20e80 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
20e90 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 file "/home/fre
20ea0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c d/data.db"..** <
20eb0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 tr><td> file://d
20ec0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 arkstar/home/fre
20ed0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a d/data.db <td> .
20ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 ** An e
20ef0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 rror. "darkstar"
20f00 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e is not a recogn
20f10 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a ized authority..
20f20 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 ** <tr><td style
20f30 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f ="white-space:no
20f40 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 wrap"> .**
20f50 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 file:///C:/D
20f60 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 ocuments%20and%2
20f70 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 0Settings/fred/D
20f80 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a esktop/data.db.*
20f90 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f * <td> Windo
20fa0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 ws only: Open th
20fb0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 e file "data.db"
20fc0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 on fred's deskt
20fd0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 op on drive.**
20fe0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 C:. Note
20ff0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 that the %20 es
21000 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 caping in this e
21010 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 xample is not st
21020 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 rictly .**
21030 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 necessary -
21040 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 space characters
21050 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 can be used lit
21060 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 erally.**
21070 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 in URI filena
21080 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e mes..** <tr><td>
21090 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f file:data.db?mo
210a0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 de=ro&cache=priv
210b0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 ate <td> .**
210c0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
210d0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 "data.db" in the
210e0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f current directo
210f0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 ry for read-only
21100 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 access..**
21110 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 Regardless
21120 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
21130 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d t shared-cache m
21140 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 ode is enabled b
21150 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 y.** de
21160 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 fault, use a pri
21170 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c vate cache..** <
21180 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
21190 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f me/fred/data.db?
211a0 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 vfs=unix-nolock
211b0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 <td>.**
211c0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d Open file "/hom
211d0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e e/fred/data.db".
211e0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c Use the special
211f0 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 VFS "unix-noloc
21200 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 k"..** <tr><td>
21210 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
21220 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 e=readonly <td>
21230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
21240 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 error. "readonly
21250 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 " is not a valid
21260 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 option for the
21270 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 "mode" parameter
21280 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a ..** </table>.**
21290 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 .** ^URI hexadec
212a0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
212b0 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 ences (%HH) are
212c0 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e supported within
212d0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a the path and.**
212e0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
212f0 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 s of a URI. A he
21300 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
21310 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 sequence consis
21320 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 ts of a.** perce
21330 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 nt sign - "%" -
21340 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 followed by exac
21350 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 tly two hexadeci
21360 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 mal digits .** s
21370 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 pecifying an oct
21380 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 et value. ^Befor
21390 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 e the path or qu
213a0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
213b0 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e f a.** URI filen
213c0 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 ame are interpre
213d0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e ted, they are en
213e0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
213f0 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 8 and all .** he
21400 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
21410 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 sequences repla
21420 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 ced by a single
21430 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 byte containing
21440 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e the.** correspon
21450 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 ding octet. If t
21460 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 his process gene
21470 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 rates an invalid
21480 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c UTF-8 encoding,
21490 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 .** the results
214a0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
214b0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
214c0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f Windows users:</
214d0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 b> The encoding
214e0 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 used for the fi
214f0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
21500 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 ** of sqlite3_op
21510 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
21520 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 _open_v2() must
21530 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 be UTF-8, not wh
21540 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 atever.** codepa
21550 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 ge is currently
21560 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 defined. Filena
21570 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 mes containing i
21580 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 nternational.**
21590 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 characters must
215a0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 be converted to
215b0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 UTF-8 prior to p
215c0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f assing them into
215d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
215e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
215f0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c en_v2()..**.** <
21600 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
21610 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a s Runtime users:
21620 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 </b> The tempor
21630 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 ary directory mu
21640 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 st be set.** pri
21650 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 or to calling sq
21660 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
21670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
21680 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 ). Otherwise, v
21690 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 arious.** featur
216a0 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 es that require
216b0 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f the use of tempo
216c0 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 rary files may f
216d0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ail..**.** See a
216e0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 lso: [sqlite3_te
216f0 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f mp_directory].*/
21700 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
21710 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
21720 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
21730 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
21740 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
21750 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
21760 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
21770 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
21780 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
21790 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
217a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a sqlite3_open16(.
217b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 const void *fi
217c0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
217d0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
217e0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c UTF-16) */. sql
217f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
21800 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
21810 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
21820 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
21830 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nt sqlite3_open_
21840 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 v2(. const char
21850 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
21860 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
21870 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
21880 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 sqlite3 **ppDb,
21890 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
218a0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
218b0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c */. int flags,
218c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
218d0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 Flags */. cons
218e0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 t char *zVfs
218f0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 /* Name of V
21900 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 FS module to use
21910 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
21920 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 PI3REF: Obtain V
21930 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 alues For URI Pa
21940 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 rameters.**.** T
21950 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 hese are utility
21960 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 routines, usefu
21970 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 l to VFS impleme
21980 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 ntations, that c
21990 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 heck.** to see i
219a0 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c f a database fil
219b0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 e was a URI that
219c0 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 contained a spe
219d0 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 cific query .**
219e0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 parameter, and i
219f0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 f so obtains the
21a00 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 value of that q
21a10 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a uery parameter..
21a20 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 **.** If F is th
21a30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e e database filen
21a40 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 ame pointer pass
21a50 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 ed into the xOpe
21a60 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a n() method of .*
21a70 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e * a VFS implemen
21a80 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 tation when the
21a90 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
21aa0 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f to xOpen() has o
21ab0 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f ne or .** more o
21ac0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
21ad0 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 EN_URI] or [SQLI
21ae0 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
21af0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a bits set and.**
21b00 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f P is the name o
21b10 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 f the query para
21b20 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 meter, then.** s
21b30 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
21b40 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
21b50 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
21b60 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 he P.** paramete
21b70 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f r if it exists o
21b80 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
21b90 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 if P does not a
21ba0 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 ppear as a .** q
21bb0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f uery parameter o
21bc0 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 n F. If P is a
21bd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
21be0 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 of F.** has no e
21bf0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 xplicit value, t
21c00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f hen sqlite3_uri_
21c10 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 parameter(F,P) r
21c20 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e eturns.** a poin
21c30 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 ter to an empty
21c40 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 string..**.** Th
21c50 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f e sqlite3_uri_bo
21c60 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
21c70 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 tine assumes tha
21c80 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e t P is a boolean
21c90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e .** parameter an
21ca0 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 d returns true (
21cb0 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 1) or false (0)
21cc0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 according to the
21cd0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 value.** of P.
21ce0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
21cf0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
21d00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
21d10 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a true (1) if the.
21d20 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 ** value of quer
21d30 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 y parameter P is
21d40 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 one of "yes", "
21d50 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 true", or "on" i
21d60 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 n any.** case or
21d70 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
21d80 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d gins with a non-
21d90 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 zero number. Th
21da0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 e .** sqlite3_ur
21db0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
21dc0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
21dd0 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 s false (0) if t
21de0 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 he value of.** q
21df0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 uery parameter P
21e00 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c is one of "no",
21e10 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 "false", or "of
21e20 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f f" in any case o
21e30 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 r.** if the valu
21e40 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 e begins with a
21e50 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 numeric zero. I
21e60 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 f P is not a que
21e70 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 ry.** parameter
21e80 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 on F or if the v
21e90 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 alue of P is doe
21ea0 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 s not match any
21eb0 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c of the.** above,
21ec0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
21ed0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
21ee0 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e returns (B!=0).
21ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
21f00 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 e3_uri_int64(F,P
21f10 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 ,D) routine conv
21f20 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f erts the value o
21f30 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 f P into a.** 64
21f40 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
21f50 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ger and returns
21f60 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 that integer, or
21f70 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 D if P does not
21f80 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 .** exist. If t
21f90 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 he value of P is
21fa0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
21fb0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 than an integer
21fc0 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 , then.** zero i
21fd0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a s returned..** .
21fe0 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c ** If F is a NUL
21ff0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
22000 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
22010 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
22020 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 ns NULL and.** s
22030 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
22040 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e an(F,P,B) return
22050 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f s B. If F is no
22060 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 t a NULL pointer
22070 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 and.** is not a
22080 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 database file p
22090 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 athname pointer
220a0 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 that SQLite pass
220b0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 ed into the xOpe
220c0 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c n.** VFS method,
220d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
220e0 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 or of this routi
220f0 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 ne is undefined
22100 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 and probably.**
22110 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a undesirable..*/.
22120 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
22130 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 char *sqlite3_u
22140 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e ri_parameter(con
22150 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
22160 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a me, const char *
22170 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f zParam);.SQLITE_
22180 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
22190 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
221a0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
221b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
221c0 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
221d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
221e0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
221f0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e e3_uri_int64(con
22200 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 st char*, const
22210 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 char*, sqlite3_i
22220 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt64);.../*.** C
22230 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
22240 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
22250 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
22260 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 ite3_errcode() i
22270 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
22280 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 the numeric [re
22290 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a sult code] or.**
222a0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
222b0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 t code] for the
222c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c most recent fail
222d0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 ed sqlite3_* API
222e0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 call.** associa
222f0 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 ted with a [data
22300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
22310 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 . If a prior API
22320 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 call failed.**
22330 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 but the most rec
22340 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 ent API call suc
22350 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 ceeded, the retu
22360 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a rn value from.**
22370 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 sqlite3_errcode
22380 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e () is undefined.
22390 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ^The sqlite3_e
223a0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
223b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
223c0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 s the same excep
223d0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 t that it always
223e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a returns the .**
223f0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
22400 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 t code] even whe
22410 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c n extended resul
22420 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 t codes are.** d
22430 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e isabled..**.** ^
22440 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d The sqlite3_errm
22450 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 sg() and sqlite3
22460 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 _errmsg16() retu
22470 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 rn English-langu
22480 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 age.** text that
22490 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 describes the e
224a0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 rror, as either
224b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 UTF-8 or UTF-16
224c0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a respectively..**
224d0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ^(Memory to hol
224e0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 d the error mess
224f0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 age string is ma
22500 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 naged internally
22510 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
22520 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 tion does not ne
22530 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 ed to worry abou
22540 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 t freeing the re
22550 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 sult..** However
22560 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 , the error stri
22570 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 ng might be over
22580 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c written or deall
22590 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 ocated by.** sub
225a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
225b0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
225c0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e terface function
225d0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 s.)^.**.** ^The
225e0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 sqlite3_errstr()
225f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
22600 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c ns the English-l
22610 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 anguage text.**
22620 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 that describes t
22630 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d he [result code]
22640 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e , as UTF-8..** ^
22650 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 (Memory to hold
22660 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 the error messag
22670 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 e string is mana
22680 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a ged internally.*
22690 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 * and must not b
226a0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 e freed by the a
226b0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a pplication)^..**
226c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 .** When the ser
226d0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
226e0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 ng mode] is in u
226f0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 se, it might be
22700 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 the.** case that
22710 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 a second error
22720 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 occurs on a sepa
22730 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 rate thread in b
22740 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 etween.** the ti
22750 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 me of the first
22760 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 error and the ca
22770 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 ll to these inte
22780 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 rfaces..** When
22790 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 that happens, th
227a0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 e second error w
227b0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 ill be reported
227c0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 since these.** i
227d0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 nterfaces always
227e0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 report the most
227f0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 recent result.
22800 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 To avoid.** thi
22810 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 s, each thread c
22820 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 an obtain exclus
22830 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b ive use of the [
22840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
22850 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 ion] D.** by inv
22860 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d oking [sqlite3_m
22870 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c utex_enter]([sql
22880 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 ite3_db_mutex](D
22890 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e )) before beginn
228a0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 ing.** to use D
228b0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 and invoking [sq
228c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 lite3_mutex_leav
228d0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d e]([sqlite3_db_m
228e0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a utex](D)) after.
228f0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 ** all calls to
22900 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c the interfaces l
22910 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 isted here are c
22920 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ompleted..**.**
22930 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 If an interface
22940 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 fails with SQLIT
22950 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d E_MISUSE, that m
22960 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 eans the interfa
22970 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 ce.** was invoke
22980 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 d incorrectly by
22990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
229a0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c . In that case,
229b0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f the.** error co
229c0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d de and message m
229d0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 ay or may not be
229e0 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f set..*/.SQLITE_
229f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
22a00 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 errcode(sqlite3
22a10 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *db);.SQLITE_API
22a20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
22a30 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 ended_errcode(sq
22a40 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
22a50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
22a60 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 r *sqlite3_errms
22a70 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c g(sqlite3*);.SQL
22a80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
22a90 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d id *sqlite3_errm
22aa0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a sg16(sqlite3*);.
22ab0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
22ac0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
22ad0 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a rrstr(int);../*.
22ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
22af0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
22b00 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
22b10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
22b20 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 nt} {prepared st
22b30 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 atements}.**.**
22b40 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
22b50 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
22b60 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 sents a single S
22b70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a QL statement..**
22b80 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 This object is
22b90 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 variously known
22ba0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 as a "prepared s
22bb0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a tatement" or a.*
22bc0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 * "compiled SQL
22bd0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 statement" or si
22be0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 mply as a "state
22bf0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment"..**.** The
22c00 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 life of a state
22c10 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 ment object goes
22c20 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 something like
22c30 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e this:.**.** <ol>
22c40 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 .** <li> Create
22c50 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
22c60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
22c70 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c e_v2()] or a rel
22c80 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e ated.** fun
22c90 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 ction..** <li> B
22ca0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 ind values to [h
22cb0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 ost parameters]
22cc0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
22cd0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 3_bind_*().**
22ce0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a interfaces..*
22cf0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 * <li> Run the S
22d00 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 QL by calling [s
22d10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
22d20 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
22d30 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 ..** <li> Reset
22d40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 the statement us
22d50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
22d60 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 et()] then go ba
22d70 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 ck.** to st
22d80 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a ep 2. Do this z
22d90 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 ero or more time
22da0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 s..** <li> Destr
22db0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 oy the object us
22dc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
22dd0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f alize()]..** </o
22de0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 l>.**.** Refer t
22df0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 o documentation
22e00 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 on individual me
22e10 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 thods above for
22e20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
22e30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 formation..*/.ty
22e40 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
22e50 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
22e60 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
22e70 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
22e80 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e e Limits.**.** ^
22e90 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 (This interface
22ea0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 allows the size
22eb0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 of various const
22ec0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 ructs to be limi
22ed0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e ted.** on a conn
22ee0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 ection by connec
22ef0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 tion basis. The
22f00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
22f10 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 is the.** [data
22f20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
22f30 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 whose limit is
22f40 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 to be set or que
22f50 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ried. The.** se
22f60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
22f70 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 s one of the [li
22f80 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 mit categories]
22f90 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a that define a.**
22fa0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 class of constr
22fb0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 ucts to be size
22fc0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 limited. The th
22fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
22fe0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 the.** new limi
22ff0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 t for that const
23000 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 ruct.)^.**.** ^I
23010 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 f the new limit
23020 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 is a negative nu
23030 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 mber, the limit
23040 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a is unchanged..**
23050 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 ^(For each limi
23060 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 t category SQLIT
23070 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c E_LIMIT_<i>NAME<
23080 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a /i> there is a .
23090 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 ** [limits | har
230a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a d upper bound].*
230b0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 * set at compile
230c0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 -time by a C pre
230d0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
230e0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 called.** [limit
230f0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c s | SQLITE_MAX_<
23100 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 i>NAME</i>]..**
23110 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 (The "_LIMIT_" i
23120 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 n the name is ch
23130 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 anged to "_MAX_"
23140 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 .))^.** ^Attempt
23150 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
23160 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
23170 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
23180 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
23190 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
231a0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 e hard upper bou
231b0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 nd..**.** ^Regar
231c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
231d0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 or not the limi
231e0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 t was changed, t
231f0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f he .** [sqlite3_
23200 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 limit()] interfa
23210 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 ce returns the p
23220 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 rior value of th
23230 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e e limit..** ^Hen
23240 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 ce, to find the
23250 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
23260 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 a limit without
23270 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a changing it,.**
23280 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 simply invoke t
23290 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 his interface wi
232a0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 th the third par
232b0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 ameter set to -1
232c0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 ..**.** Run-time
232d0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 limits are inte
232e0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
232f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
23300 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 t manage.** both
23310 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 their own inter
23320 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 nal database and
23330 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 also databases
23340 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c that are control
23350 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 led.** by untrus
23360 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 ted external sou
23370 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c rces. An exampl
23380 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
23390 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 ght be a.** web
233a0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
233b0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
233c0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
233d0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
233e0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
233f0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
23400 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
23410 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
23420 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
23430 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
23440 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
23450 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
23460 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
23470 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
23480 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
23490 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
234a0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
234b0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
234c0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
234d0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
234e0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
234f0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
23500 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
23510 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
23520 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
23530 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
23540 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
23550 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
23560 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
23570 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
23580 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
23590 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
235a0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
235b0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
235c0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
235d0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
235e0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
235f0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
23600 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
23610 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
23620 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
23630 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d int sqlite3_lim
23640 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 it(sqlite3*, int
23650 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 id, int newVal)
23660 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
23670 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 F: Run-Time Limi
23680 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 t Categories.**
23690 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 KEYWORDS: {limit
236a0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d category} {*lim
236b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a it categories}.*
236c0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
236d0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 ants define vari
236e0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 ous performance
236f0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 limits.** that c
23700 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 an be lowered at
23710 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 run-time using
23720 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
23730 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 ]..** The synops
23740 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e is of the meanin
23750 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 gs of the variou
23760 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 s limits is show
23770 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 n below..** Addi
23780 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
23790 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 on is available
237a0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d at [limits | Lim
237b0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a its in SQLite]..
237c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
237d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e SQLITE_LIMIT_LEN
237e0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 GTH]] ^(<dt>SQLI
237f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c TE_LIMIT_LENGTH<
23800 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
23810 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 maximum size of
23820 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c any string or BL
23830 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c OB or table row,
23840 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e in bytes.<dd>)^
23850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
23860 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
23870 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
23880 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
23890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
238a0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
238b0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d of an SQL statem
238c0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f ent, in bytes.</
238d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
238e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d LITE_LIMIT_COLUM
238f0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 N]] ^(<dt>SQLITE
23900 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 _LIMIT_COLUMN</d
23910 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
23920 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
23930 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 columns in a tab
23940 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 le definition or
23950 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c in the.** resul
23960 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
23970 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d CT] or the maxim
23980 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c um number of col
23990 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 umns in an index
239a0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 .** or in an ORD
239b0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 ER BY or GROUP B
239c0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e Y clause.</dd>)^
239d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
239e0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
239f0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
23a00 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
23a10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
23a20 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f maximum depth o
23a30 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 f the parse tree
23a40 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 on any expressi
23a50 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a on.</dd>)^.**.**
23a60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
23a70 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d COMPOUND_SELECT]
23a80 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
23a90 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
23aa0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LECT</dt>.** <dd
23ab0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d >The maximum num
23ac0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 ber of terms in
23ad0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 a compound SELEC
23ae0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 T statement.</dd
23af0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
23b00 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
23b10 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
23b20 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 LIMIT_VDBE_OP</d
23b30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
23b40 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
23b50 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 instructions in
23b60 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e a virtual machin
23b70 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 e program.** use
23b80 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
23b90 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
23ba0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 This limit is
23bb0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a not currently.**
23bc0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 enforced, thoug
23bd0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 h that might be
23be0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 added in some fu
23bf0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a ture release of.
23c00 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 ** SQLite.</dd>)
23c10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
23c20 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
23c30 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ARG]] ^(<dt>SQLI
23c40 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
23c50 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 N_ARG</dt>.** <d
23c60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
23c70 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
23c80 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e s on a function.
23c90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
23ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
23cb0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 ACHED]] ^(<dt>SQ
23cc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
23cd0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HED</dt>.** <dd>
23ce0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
23cf0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 er of [ATTACH |
23d00 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
23d10 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a es].)^</dd>.**.*
23d20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
23d30 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
23d40 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e NGTH]].** ^(<dt>
23d50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
23d60 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
23d70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
23d80 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
23d90 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 of the pattern a
23da0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
23db0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f LIKE] or.** [GLO
23dc0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 B] operators.</d
23dd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
23de0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
23df0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e LE_NUMBER]].** ^
23e00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
23e10 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
23e20 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 R</dt>.** <dd>Th
23e30 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 e maximum index
23e40 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 number of any [p
23e50 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 arameter] in an
23e60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e SQL statement.)^
23e70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
23e80 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
23e90 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 PTH]] ^(<dt>SQLI
23ea0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
23eb0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c _DEPTH</dt>.** <
23ec0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 dd>The maximum d
23ed0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f epth of recursio
23ee0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c n for triggers.<
23ef0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
23f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
23f10 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
23f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
23f30 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
23f40 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
23f50 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
23f60 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
23f70 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
23f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
23f90 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
23fa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
23fb0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
23fc0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
23fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
23fe0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
23ff0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
24000 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
24010 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
24020 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
24030 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
24040 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
24050 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
24060 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
24070 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
24080 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
24090 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
240a0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
240b0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
240c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
240d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
240e0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 9.#de
240f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
24100 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 T_TRIGGER_DEPTH
24110 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 10../
24120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
24130 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 ompiling An SQL
24140 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 Statement.** KEY
24150 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 WORDS: {SQL stat
24160 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a ement compiler}.
24170 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 **.** To execute
24180 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 an SQL query, i
24190 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 t must first be
241a0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 compiled into a
241b0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f byte-code.** pro
241c0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f gram using one o
241d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
241e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
241f0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 t argument, "db"
24200 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 , is a [database
24210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 connection] obt
24220 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 ained from a.**
24230 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c prior successful
24240 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
24250 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
24260 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f te3_open_v2()] o
24270 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
24280 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 en16()]. The da
24290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
242a0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 n must not have
242b0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a been closed..**.
242c0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
242d0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 gument, "zSql",
242e0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 is the statement
242f0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c to be compiled,
24300 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 encoded.** as e
24310 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
24320 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 TF-16. The sqli
24330 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e te3_prepare() an
24340 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
24350 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 e_v2().** interf
24360 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 aces use UTF-8,
24370 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
24380 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 are16() and sqli
24390 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
243a0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 ().** use UTF-16
243b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
243c0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
243d0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f s less than zero
243e0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 , then zSql is r
243f0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a ead up to the.**
24400 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d first zero term
24410 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 inator. ^If nByt
24420 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 e is non-negativ
24430 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 e, then it is th
24440 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d e maximum.** num
24450 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 ber of bytes re
24460 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e ad from zSql. ^
24470 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f When nByte is no
24480 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a n-negative, the.
24490 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 ** zSql string e
244a0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 nds at either th
244b0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f e first '\000' o
244c0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 r '\u0000' chara
244d0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e cter or.** the n
244e0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 Byte-th byte, wh
244f0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 ichever comes fi
24500 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c rst. If the call
24510 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 er knows.** that
24520 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 the supplied st
24530 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d ring is nul-term
24540 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 inated, then the
24550 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a re is a small.**
24560 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 performance adv
24570 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 antage to be gai
24580 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 ned by passing a
24590 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 n nByte paramete
245a0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 r that.** is equ
245b0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 al to the number
245c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
245d0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 input string <i
245e0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a >including</i>.*
245f0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e * the nul-termin
24600 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 ator bytes as th
24610 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 is saves SQLite
24620 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a from having to.*
24630 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 * make a copy of
24640 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e the input strin
24650 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 g..**.** ^If pzT
24660 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 ail is not NULL
24670 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 then *pzTail is
24680 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
24690 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a the first byte.
246a0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 ** past the end
246b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c of the first SQL
246c0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
246d0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 ql. These routi
246e0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 nes only.** comp
246f0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 ile the first st
24700 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c atement in zSql,
24710 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c so *pzTail is l
24720 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a eft pointing to.
24730 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 ** what remains
24740 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a uncompiled..**.*
24750 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 * ^*ppStmt is le
24760 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 ft pointing to a
24770 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 compiled [prepa
24780 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
24790 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 hat can be.** ex
247a0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 ecuted using [sq
247b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 lite3_step()].
247c0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 ^If there is an
247d0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 error, *ppStmt i
247e0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c s set.** to NULL
247f0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 . ^If the input
24800 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e text contains n
24810 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e o SQL (if the in
24820 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a put is an empty.
24830 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 ** string or a c
24840 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 omment) then *pp
24850 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e Stmt is set to N
24860 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c ULL..** The call
24870 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 ing procedure is
24880 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
24890 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f deleting the co
248a0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 mpiled.** SQL st
248b0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 atement using [s
248c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
248d0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 )] after it has
248e0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 finished with it
248f0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 ..** ppStmt may
24900 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a not be NULL..**.
24910 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 ** ^On success,
24920 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 the sqlite3_prep
24930 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 are() family of
24940 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 routines return
24950 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 [SQLITE_OK];.**
24960 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 otherwise an [er
24970 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
24980 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 urned..**.** The
24990 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
249a0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 _v2() and sqlite
249b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
249c0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a interfaces are.
249d0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 ** recommended f
249e0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 or all new progr
249f0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 ams. The two old
24a00 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 er interfaces ar
24a10 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f e retained.** fo
24a20 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 r backwards comp
24a30 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 atibility, but t
24a40 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 heir use is disc
24a50 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 ouraged..** ^In
24a60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
24a70 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 ces, the prepare
24a80 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 d statement.** t
24a90 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 hat is returned
24aa0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 (the [sqlite3_st
24ab0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 mt] object) cont
24ac0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 ains a copy of t
24ad0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 he.** original S
24ae0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 QL text. This ca
24af0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 uses the [sqlite
24b00 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 3_step()] interf
24b10 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 ace to.** behave
24b20 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 differently in
24b30 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a three ways:.**.*
24b40 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a * <ol>.** <li>.*
24b50 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 * ^If the databa
24b60 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 se schema change
24b70 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 s, instead of re
24b80 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
24b90 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a SCHEMA] as it.**
24ba0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 always used to
24bb0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 do, [sqlite3_ste
24bc0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 p()] will automa
24bd0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c tically recompil
24be0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 e the SQL.** sta
24bf0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 tement and try t
24c00 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a o run it again..
24c10 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c ** </li>.**.** <
24c20 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 li>.** ^When an
24c30 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 error occurs, [s
24c40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
24c50 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f ill return one o
24c60 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a f the detailed.*
24c70 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 * [error codes]
24c80 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 or [extended err
24c90 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 or codes]. ^The
24ca0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 legacy behavior
24cb0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 was that.** [sq
24cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f lite3_step()] wo
24cd0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 uld only return
24ce0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 a generic [SQLIT
24cf0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 E_ERROR] result
24d00 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 code.** and the
24d10 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c application woul
24d20 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 d have to make a
24d30 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 second call to
24d40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
24d50 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f ].** in order to
24d60 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c find the underl
24d70 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 ying cause of th
24d80 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 e problem. With
24d90 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 the "v2" prepare
24da0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 .** interfaces,
24db0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 the underlying r
24dc0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 eason for the er
24dd0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 ror is returned
24de0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 immediately..**
24df0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
24e00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 .** ^If the spec
24e10 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 ific value bound
24e20 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c to [parameter |
24e30 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d host parameter]
24e40 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 in the .** WHER
24e50 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 E clause might i
24e60 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f nfluence the cho
24e70 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 ice of query pla
24e80 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e n for a statemen
24e90 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 t,.** then the s
24ea0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 tatement will be
24eb0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
24ec0 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 ecompiled, as if
24ed0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 there had been
24ee0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 .** a schema cha
24ef0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 nge, on the firs
24f00 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 t [sqlite3_step
24f10 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 ()] call followi
24f20 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a ng any change.**
24f30 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
24f40 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e _bind_text | bin
24f50 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b dings] of that [
24f60 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 parameter]. .**
24f70 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 ^The specific va
24f80 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 lue of WHERE-cla
24f90 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 use [parameter]
24fa0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 might influence
24fb0 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f the .** choice o
24fc0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 f query plan if
24fd0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 the parameter is
24fe0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 the left-hand s
24ff0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a ide of a [LIKE].
25000 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 ** or [GLOB] ope
25010 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 rator or if the
25020 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d parameter is com
25030 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 pared to an inde
25040 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e xed column.** an
25050 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e d the [SQLITE_EN
25060 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 ABLE_STAT3] comp
25070 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
25080 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 is enabled..** t
25090 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 he .** </li>.**
250a0 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ol>.*/.SQLITE_
250b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
250c0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 prepare(. sqlit
250d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
250e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
250f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
25100 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
25110 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
25120 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
25130 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
25140 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
25150 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
25160 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
25170 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
25180 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
25190 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
251a0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
251b0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
251c0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
251d0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
251e0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
251f0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
25200 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 I int sqlite3_pr
25210 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 epare_v2(. sqli
25220 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
25230 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
25240 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
25250 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
25260 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
25270 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
25280 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
25290 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
252a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
252b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
252c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
252d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
252e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
252f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
25300 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
25310 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
25320 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
25330 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
25340 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 l */.);.SQLITE_A
25350 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 PI int sqlite3_p
25360 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
25370 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
25380 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
25390 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
253a0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
253b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
253c0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
253d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
253e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
253f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
25400 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
25410 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
25420 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
25430 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
25440 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
25450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
25460 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
25470 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
25480 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
25490 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
254a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
254b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 prepare16_v2(.
254c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
254d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
254e0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
254f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
25500 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
25510 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
25520 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
25530 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
25540 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
25550 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
25560 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
25570 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
25580 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
25590 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
255a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
255b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
255c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
255d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
255e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a f zSql */.);../*
255f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
25600 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 trieving Stateme
25610 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 nt SQL.**.** ^Th
25620 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e is interface can
25630 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 be used to retr
25640 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 ieve a saved cop
25650 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 y of the origina
25660 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 l.** SQL text us
25670 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b ed to create a [
25680 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25690 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 nt] if that stat
256a0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d ement was.** com
256b0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 piled using eith
256c0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 er [sqlite3_prep
256d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 are_v2()] or [sq
256e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
256f0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 v2()]..*/.SQLITE
25700 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
25710 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c *sqlite3_sql(sql
25720 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
25730 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
25740 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
25750 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
25760 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 t Writes The Dat
25770 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 abase.**.** ^The
25780 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
25790 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 adonly(X) interf
257a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
257b0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a (non-zero) if.*
257c0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 * and only if th
257d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
257e0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e ement] X makes n
257f0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 o direct changes
25800 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 to.** the conte
25810 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
25820 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e se file..**.** N
25830 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 ote that [applic
25840 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
25850 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a L functions] or.
25860 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
25870 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 es] might change
25880 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e the database in
25890 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 directly as a si
258a0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 de effect. .**
258b0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 ^(For example, i
258c0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
258d0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 defines a funct
258e0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 ion "eval()" tha
258f0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c t .** calls [sql
25900 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 ite3_exec()], th
25910 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 en the following
25920 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
25930 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ould.** change t
25940 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
25950 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 through side-ef
25960 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c fects:.**.** <bl
25970 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
25980 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c * SELECT eval
25990 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 ('DELETE FROM t1
259a0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c ') FROM t2;.** <
259b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
259c0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 e>.**.** But bec
259d0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 ause the [SELECT
259e0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 ] statement does
259f0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
25a00 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a database file.**
25a10 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 directly, sqlit
25a20 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
25a30 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 () would still r
25a40 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a eturn true.)^.**
25a50 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e .** ^Transaction
25a60 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 control stateme
25a70 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 nts such as [BEG
25a80 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b IN], [COMMIT], [
25a90 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 ROLLBACK],.** [S
25aa0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b AVEPOINT], and [
25ab0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 RELEASE] cause s
25ac0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
25ad0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
25ae0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 true,.** since
25af0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 the statements t
25b00 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 hemselves do not
25b10 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 actually modify
25b20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 the database bu
25b30 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 t.** rather they
25b40 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d control the tim
25b50 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 ing of when othe
25b60 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 r statements mod
25b70 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 ify the .** data
25b80 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 base. ^The [ATT
25b90 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 ACH] and [DETACH
25ba0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 ] statements als
25bb0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 o cause.** sqlit
25bc0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
25bd0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
25be0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 e since, while t
25bf0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a hose statements.
25c00 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f ** change the co
25c10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 nfiguration of a
25c20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
25c30 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f tion, they do no
25c40 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 t make .** chang
25c50 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e es to the conten
25c60 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
25c70 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e e files on disk.
25c80 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
25c90 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
25ca0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 readonly(sqlite3
25cb0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
25cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
25cd0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 Determine If A P
25ce0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
25cf0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 t Has Been Reset
25d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
25d10 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
25d20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
25d30 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
25d40 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 o) if the.** [pr
25d50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
25d60 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 ] S has been ste
25d70 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e pped at least on
25d80 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 ce using .** [sq
25d90 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 lite3_step(S)] b
25da0 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 ut has not run t
25db0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 o completion and
25dc0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 /or has not .**
25dd0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 been reset using
25de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
25df0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 S)]. ^The sqlit
25e00 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a e3_stmt_busy(S).
25e10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
25e20 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 urns false if S
25e30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
25e40 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 r. If S is not
25e50 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a .** NULL point
25e60 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 er and is not a
25e70 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c pointer to a val
25e80 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 id [prepared sta
25e90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
25ea0 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 t, then the beha
25eb0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
25ec0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 d and probably u
25ed0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a ndesirable..**.*
25ee0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
25ef0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 can be used in
25f00 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c combination [sql
25f10 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 ite3_next_stmt()
25f20 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 ].** to locate a
25f30 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ll prepared stat
25f40 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 ements associate
25f50 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 d with a databas
25f60 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e e .** connection
25f70 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 that are in nee
25f80 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 d of being reset
25f90 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 . This can be u
25fa0 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d sed,.** for exam
25fb0 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 ple, in diagnost
25fc0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 ic routines to s
25fd0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 earch for prepar
25fe0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ed .** statement
25ff0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 s that are holdi
26000 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e ng a transaction
26010 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 open..*/.SQLITE
26020 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
26030 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 _stmt_busy(sqlit
26040 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
26050 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 * CAPI3REF: Dyna
26060 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 mically Typed Va
26070 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 lue Object.** KE
26080 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 YWORDS: {protect
26090 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
260a0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 } {unprotected s
260b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a qlite3_value}.**
260c0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 .** SQLite uses
260d0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 the sqlite3_valu
260e0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 e object to repr
260f0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 esent all values
26100 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 .** that can be
26110 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 stored in a data
26120 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 base table. SQLi
26130 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
26140 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 typing.** for th
26150 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 e values it stor
26160 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f es. ^Values sto
26170 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 red in sqlite3_v
26180 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 alue objects.**
26190 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c can be integers,
261a0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 floating point
261b0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c values, strings,
261c0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e BLOBs, or NULL.
261d0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 .**.** An sqlite
261e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 3_value object m
261f0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 ay be either "pr
26200 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 otected" or "unp
26210 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f rotected"..** So
26220 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 me interfaces re
26230 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 quire a protecte
26240 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
26250 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 Other interfac
26260 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 es.** will accep
26270 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 t either a prote
26280 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f cted or an unpro
26290 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
262a0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 alue..** Every i
262b0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 nterface that ac
262c0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 cepts sqlite3_va
262d0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 lue arguments sp
262e0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 ecifies.** wheth
262f0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 er or not it req
26300 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 uires a protecte
26310 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
26320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 .**.** The terms
26330 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 "protected" and
26340 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 "unprotected" r
26350 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 efer to whether
26360 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 or not.** a mute
26370 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 x is held. An i
26380 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
26390 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
263a0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
263b0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
263c0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
263d0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
263e0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
263f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
26400 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
26410 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
26420 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
26430 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
26440 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
26450 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
26460 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
26470 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
26480 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
26490 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
264a0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
264b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
264c0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
264d0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
264e0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
264f0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
26500 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
26510 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
26520 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
26530 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
26540 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
26550 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
26560 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
26570 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
26580 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
26590 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
265a0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
265b0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
265c0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
265d0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
265e0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
265f0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
26600 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
26610 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e ects even when n
26620 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 ot strictly requ
26630 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ired..**.** ^The
26640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
26650 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
26660 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
26670 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
26680 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
26690 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
266a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
266b0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
266c0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 cted..** ^The sq
266d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
266e0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
266f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
26700 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
26710 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
26720 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
26730 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
26740 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
26750 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
26760 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
26770 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
26780 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ind_value()]..**
26790 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
267a0 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 lue_blob | sqlit
267b0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d e3_value_type()]
267c0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e family of.** in
267d0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
267e0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
267f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
26800 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
26810 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
26820 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
26830 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
26840 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
26850 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ect.**.** The co
26860 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 ntext in which a
26870 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 n SQL function e
26880 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 xecutes is store
26890 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 d in an.** sqlit
268a0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
268b0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 t. ^A pointer t
268c0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
268d0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
268e0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
268f0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
26900 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
26910 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
26920 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
26930 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
26940 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
26950 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
26960 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
26970 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
26980 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
26990 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
269a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
269b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
269c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
269d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
269e0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
269f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
26a00 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
26a10 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
26a20 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
26a30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
26a40 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
26a50 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
26a60 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
26a70 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
26a80 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
26a90 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
26aa0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
26ab0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
26ac0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 host parameter}
26ad0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 {host parameters
26ae0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
26af0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f r name}.** KEYWO
26b00 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 RDS: {SQL parame
26b10 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 ter} {SQL parame
26b20 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 ters} {parameter
26b30 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 binding}.**.**
26b40 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 ^(In the SQL sta
26b50 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 tement text inpu
26b60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 t to [sqlite3_pr
26b70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 epare_v2()] and
26b80 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a its variants,.**
26b90 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 literals may be
26ba0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b replaced by a [
26bb0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 parameter] that
26bc0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 matches one of f
26bd0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 ollowing.** temp
26be0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c lates:.**.** <ul
26bf0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 >.** <li> ?.**
26c00 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c <li> ?NNN.** <l
26c10 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> :VVV.** <li>
26c20 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 @VVV.** <li>
26c30 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a $VVV.** </ul>.**
26c40 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c .** In the templ
26c50 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 ates above, NNN
26c60 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e represents an in
26c70 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a teger literal,.*
26c80 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 * and VVV repres
26c90 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d ents an alphanum
26ca0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e eric identifier.
26cb0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 )^ ^The values
26cc0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 of these.** para
26cd0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c meters (also cal
26ce0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 led "host parame
26cf0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 ter names" or "S
26d00 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a QL parameters").
26d10 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 ** can be set us
26d20 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
26d30 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
26d40 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a s defined here..
26d50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
26d60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
26d70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 sqlite3_bind_*(
26d80 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c ) routines is al
26d90 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 ways.** a pointe
26da0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 r to the [sqlite
26db0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 3_stmt] object r
26dc0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 eturned from.**
26dd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
26de0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 _v2()] or its va
26df0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 riants..**.** ^T
26e00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
26e10 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
26e20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d of the SQL param
26e30 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a eter to be set..
26e40 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 ** ^The leftmost
26e50 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 SQL parameter h
26e60 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
26e70 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d . ^When the sam
26e80 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 e named.** SQL p
26e90 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 arameter is used
26ea0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c more than once,
26eb0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 second and subs
26ec0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 equent.** occurr
26ed0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 ences have the s
26ee0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 ame index as the
26ef0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 first occurrenc
26f00 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 e..** ^The index
26f10 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d for named param
26f20 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f eters can be loo
26f30 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 ked up using the
26f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
26f50 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
26f60 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 x()] API if desi
26f70 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 red. ^The index
26f80 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 .** for "?NNN" p
26f90 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 arameters is the
26fa0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a value of NNN..*
26fb0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 * ^The NNN value
26fc0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e must be between
26fd0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 1 and the [sqli
26fe0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
26ff0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 parameter [SQLIT
27000 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
27010 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c _NUMBER] (defaul
27020 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a t value: 999)..*
27030 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
27040 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 argument is the
27050 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f value to bind to
27060 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a the parameter..
27070 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 **.** ^(In those
27080 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 routines that h
27090 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 ave a fourth arg
270a0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 ument, its value
270b0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
270c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
270d0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f e parameter. To
270e0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 be clear: the v
270f0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
27100 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 umber of <u>byte
27110 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c s</u> in the val
27120 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ue, not the numb
27130 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
27140 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .)^.** ^If the f
27150 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
27160 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
27170 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
27180 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 3_bind_text16().
27190 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 ** is negative,
271a0 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 then the length
271b0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 of the string is
271c0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f .** the number o
271d0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 f bytes up to th
271e0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 e first zero ter
271f0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 minator..** If t
27200 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
27210 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
27220 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 ind_blob() is ne
27230 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 gative, then.**
27240 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
27250 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 undefined..** If
27260 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 a non-negative
27270 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
27280 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 is provided to
27290 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
272a0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 t().** or sqlite
272b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 3_bind_text16()
272c0 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 then that parame
272d0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 ter must be the
272e0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 byte offset.** w
272f0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 here the NUL ter
27300 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 minator would oc
27310 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 cur assuming the
27320 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c string were NUL
27330 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 .** terminated.
27340 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
27350 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 acters occur at
27360 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 byte offsets les
27370 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 s than .** the v
27380 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 alue of the four
27390 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 th parameter the
273a0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 n the resulting
273b0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c string value wil
273c0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 l.** contain emb
273d0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 edded NULs. The
273e0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 result of expre
273f0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 ssions involving
27400 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 strings.** with
27410 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 embedded NULs i
27420 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
27430 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
27440 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
27450 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 3_bind_blob(), s
27460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
27470 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 (), and.** sqlit
27480 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
27490 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
274a0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
274b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
274c0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 ** string after
274d0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 SQLite has finis
274e0 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 hed with it. ^T
274f0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
27500 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 called.** to di
27510 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
27520 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e B or string even
27530 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 if the call to
27540 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
27550 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f b(),.** sqlite3_
27560 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 bind_text(), or
27570 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
27580 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a t16() fails. .*
27590 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
275a0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 argument is.** t
275b0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 he special value
275c0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d [SQLITE_STATIC]
275d0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 , then SQLite as
275e0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
275f0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
27600 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 in static, unma
27610 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 naged space and
27620 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
27630 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 be freed..** ^I
27640 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 f the fifth argu
27650 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c ment has the val
27660 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 ue [SQLITE_TRANS
27670 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 IENT], then.** S
27680 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 QLite makes its
27690 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 own private copy
276a0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d of the data imm
276b0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 ediately, before
276c0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f .** the sqlite3_
276d0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
276e0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
276f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
27700 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 d_zeroblob() rou
27710 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f tine binds a BLO
27720 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 B of length N th
27730 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 at.** is filled
27740 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 with zeroes. ^A
27750 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 zeroblob uses a
27760 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 fixed amount of
27770 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 memory.** (just
27780 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 an integer to h
27790 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 old its size) wh
277a0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 ile it is being
277b0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 processed..** Ze
277c0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 roblobs are inte
277d0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 nded to serve as
277e0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
277f0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a r BLOBs whose.**
27800 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 content is late
27810 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a r written using.
27820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
27830 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
27840 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f tal BLOB I/O] ro
27850 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 utines..** ^A ne
27860 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 gative value for
27870 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 the zeroblob re
27880 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d sults in a zero-
27890 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a length BLOB..**.
278a0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 ** ^If any of th
278b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
278c0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 () routines are
278d0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
278e0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f LL pointer.** fo
278f0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
27900 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 statement] or wi
27910 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 th a prepared st
27920 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 atement for whic
27930 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 h.** [sqlite3_st
27940 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 ep()] has been c
27950 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e alled more recen
27960 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 tly than [sqlite
27970 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 3_reset()],.** t
27980 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c hen the call wil
27990 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
279a0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e _MISUSE]. If an
279b0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 y sqlite3_bind_(
279c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 ).** routine is
279d0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 passed a [prepar
279e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
279f0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 at has been fina
27a00 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 lized, the.** re
27a10 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
27a20 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 d and probably h
27a30 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 armful..**.** ^B
27a40 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 indings are not
27a50 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b cleared by the [
27a60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
27a70 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e routine..** ^Un
27a80 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
27a90 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
27aa0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 as NULL..**.**
27ab0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
27ac0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 d_* routines ret
27ad0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
27ae0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e on success or an
27af0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d .** [error code]
27b00 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 if anything goe
27b10 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 s wrong..** ^[SQ
27b20 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 LITE_RANGE] is r
27b30 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 eturned if the p
27b40 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 arameter.** inde
27b50 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 x is out of rang
27b60 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d e. ^[SQLITE_NOM
27b70 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 EM] is returned
27b80 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c if malloc() fail
27b90 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 s..**.** See als
27ba0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 o: [sqlite3_bind
27bb0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 _parameter_count
27bc0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
27bd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
27be0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 name()], and [sq
27bf0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
27c00 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
27c10 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
27c20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
27c30 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
27c40 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
27c50 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 d*, int n, void(
27c60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
27c70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
27c80 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 e3_bind_double(s
27c90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
27ca0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 t, double);.SQLI
27cb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
27cc0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 e3_bind_int(sqli
27cd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
27ce0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
27cf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
27d00 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f d_int64(sqlite3_
27d10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 stmt*, int, sqli
27d20 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 te3_int64);.SQLI
27d30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
27d40 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c e3_bind_null(sql
27d50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
27d60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
27d70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
27d80 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
27d90 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 , int, const cha
27da0 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 r*, int n, void(
27db0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
27dc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
27dd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 e3_bind_text16(s
27de0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
27df0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
27e00 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 int, void(*)(voi
27e10 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 d*));.SQLITE_API
27e20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
27e30 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f d_value(sqlite3_
27e40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
27e50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t sqlite3_value*
27e60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
27e70 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a t sqlite3_bind_z
27e80 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
27e90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 stmt*, int, int
27ea0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 n);../*.** CAPI3
27eb0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 REF: Number Of S
27ec0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a QL Parameters.**
27ed0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
27ee0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
27ef0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
27f00 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 of [SQL paramet
27f10 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 ers].** in a [pr
27f20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
27f30 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 ]. SQL paramete
27f40 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 rs are tokens of
27f50 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 the.** form "?"
27f60 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 , "?NNN", ":AAA"
27f70 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 , "$AAA", or "@A
27f80 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 AA" that serve a
27f90 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 s.** placeholder
27fa0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 s for values tha
27fb0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 t are [sqlite3_b
27fc0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 ind_blob | bound
27fd0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 ].** to the para
27fe0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 meters at a late
27ff0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 r time..**.** ^(
28000 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
28010 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
28020 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
28030 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
28040 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
28050 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
28060 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
28070 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
28080 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
28090 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
280a0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
280b0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
280c0 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 NN form are used
280d0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 ,.** there may b
280e0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 e gaps in the li
280f0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 st.)^.**.** See
28100 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
28110 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
28120 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
28130 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
28140 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
28150 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
28160 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
28170 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ex()]..*/.SQLITE
28180 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
28190 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
281a0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
281b0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
281c0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
281d0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a Host Parameter.
281e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
281f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
28200 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 r_name(P,N) inte
28210 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a rface returns.**
28220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
28230 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d N-th [SQL param
28240 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 eter] in the [pr
28250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28260 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 ] P..** ^(SQL pa
28270 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
28280 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 form "?NNN" or "
28290 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
282a0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 or "$AAA".** hav
282b0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 e a name which i
282c0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e s the string "?N
282d0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
282e0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
282f0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ".** respectivel
28300 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 y..** In other w
28310 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 ords, the initia
28320 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 l ":" or "$" or
28330 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 "@" or "?".** is
28340 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 included as par
28350 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e t of the name.)^
28360 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 .** ^Parameters
28370 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 of the form "?"
28380 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 without a follow
28390 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 ing integer have
283a0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 no name.** and
283b0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 are referred to
283c0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 as "nameless" or
283d0 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 "anonymous para
283e0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e meters"..**.** ^
283f0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 The first host p
28400 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 arameter has an
28410 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 index of 1, not
28420 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 0..**.** ^If the
28430 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 value N is out
28440 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 of range or if t
28450 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 he N-th paramete
28460 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 r is.** nameless
28470 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 , then NULL is r
28480 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 eturned. ^The r
28490 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
284a0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 s.** always in U
284b0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 TF-8 encoding ev
284c0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 en if the named
284d0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a parameter was.**
284e0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 originally spec
284f0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 ified as UTF-16
28500 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 in [sqlite3_prep
28510 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b are16()] or.** [
28520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
28530 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
28540 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
28550 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
28560 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
28570 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
28580 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
28590 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
285a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
285b0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
285c0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
285d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e har *sqlite3_bin
285e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
285f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
28600 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 int);../*.** CAP
28610 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 I3REF: Index Of
28620 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 A Parameter With
28630 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a A Given Name.**
28640 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 .** ^Return the
28650 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
28660 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
28670 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a its name. ^The.
28680 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 ** index value r
28690 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 eturned is suita
286a0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 ble for use as t
286b0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 he second.** par
286c0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
286d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
286e0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e ite3_bind()]. ^
286f0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 A zero.** is ret
28700 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 urned if no matc
28710 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 hing parameter i
28720 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 s found. ^The p
28730 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
28740 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
28750 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
28760 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
28770 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
28780 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
28790 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
287a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
287b0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
287c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
287d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
287e0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
287f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
28800 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
28810 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
28820 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
28830 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c index()]..*/.SQL
28840 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
28850 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
28860 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 er_index(sqlite3
28870 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 _stmt*, const ch
28880 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a ar *zName);../*.
28890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
288a0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 et All Bindings
288b0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 On A Prepared St
288c0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 atement.**.** ^C
288d0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 ontrary to the i
288e0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 ntuition of many
288f0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 , [sqlite3_reset
28900 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 ()] does not res
28910 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 et.** the [sqlit
28920 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 e3_bind_blob | b
28930 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 indings] on a [p
28940 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
28950 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 t]..** ^Use this
28960 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 routine to rese
28970 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d t all host param
28980 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a eters to NULL..*
28990 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
289a0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 sqlite3_clear_b
289b0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
289c0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
289d0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
289e0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 Of Columns In A
289f0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a Result Set.**.**
28a00 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d ^Return the num
28a10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
28a20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 n the result set
28a30 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
28a40 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
28a50 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 atement]. ^This
28a60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
28a70 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 0 if pStmt is an
28a80 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
28a90 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 t that does not
28aa0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 return data (for
28ab0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 example an [UPD
28ac0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 ATE])..**.** See
28ad0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
28ae0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f data_count()].*/
28af0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
28b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
28b10 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
28b20 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
28b30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
28b40 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
28b50 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e sult Set.**.** ^
28b60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
28b70 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
28b80 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
28b90 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
28ba0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
28bb0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
28bc0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 ] statement. ^T
28bd0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
28be0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
28bf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
28c00 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
28c10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
28c20 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
28c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
28c40 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
28c50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
28c60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
28c70 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
28c80 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 . ^The first pa
28c90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
28ca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
28cb0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
28cc0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
28cd0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e CT] statement. ^
28ce0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
28cf0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
28d00 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e olumn number. ^
28d10 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
28d20 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
28d30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
28d40 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
28d50 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
28d60 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
28d70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
28d80 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
28d90 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
28da0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
28db0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
28dc0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
28dd0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
28de0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
28df0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
28e00 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
28e10 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
28e20 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
28e30 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
28e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
28e50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
28e60 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
28e70 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
28e80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 .**.** ^If sqlit
28e90 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
28ea0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
28eb0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
28ec0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
28ed0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
28ee0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
28ef0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
28f00 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
28f10 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
28f20 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
28f30 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
28f40 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
28f50 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
28f60 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
28f70 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
28f80 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
28f90 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
28fa0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
28fb0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
28fc0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
28fd0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
28fe0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
28ff0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
29000 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
29010 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 the next..*/.SQ
29020 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
29030 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
29040 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 umn_name(sqlite3
29050 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
29060 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
29070 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
29080 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c olumn_name16(sql
29090 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
290a0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 N);../*.** CAPI3
290b0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 REF: Source Of D
290c0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 ata In A Query R
290d0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 esult.**.** ^The
290e0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 se routines prov
290f0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 ide a means to d
29100 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 etermine the dat
29110 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
29120 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d d.** table colum
29130 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 n that is the or
29140 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 igin of a partic
29150 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 ular result colu
29160 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 mn in.** [SELECT
29170 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 ] statement..**
29180 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 ^The name of the
29190 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 database or tab
291a0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e le or column can
291b0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a be returned as.
291c0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d ** either a UTF-
291d0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 8 or UTF-16 stri
291e0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 ng. ^The _datab
291f0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 ase_ routines re
29200 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 turn.** the data
29210 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f base name, the _
29220 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 table_ routines
29230 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 return the table
29240 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 name, and.** th
29250 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e e origin_ routin
29260 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f es return the co
29270 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 lumn name..** ^T
29280 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
29290 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 ng is valid unti
292a0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 l the [prepared
292b0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 statement] is de
292c0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 stroyed.** using
292d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
292e0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 ze()] or until t
292f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
29300 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
29310 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 reprepared by t
29320 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f he first call to
29330 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
29340 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c ] for a particul
29350 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 ar run.** or unt
29360 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f il the same info
29370 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 rmation is reque
29380 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e sted.** again in
29390 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 a different enc
293a0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 oding..**.** ^Th
293b0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 e names returned
293c0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 are the origina
293d0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d l un-aliased nam
293e0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 es of the.** dat
293f0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e abase, table, an
29400 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 d column..**.**
29410 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
29420 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 ent to these int
29430 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 erfaces is a [pr
29440 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
29450 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e ]..** ^These fun
29460 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e ctions return in
29470 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 formation about
29480 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 the Nth result c
29490 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
294a0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 y.** the stateme
294b0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 nt, where N is t
294c0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 he second functi
294d0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 on argument..**
294e0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 ^The left-most c
294f0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 olumn is column
29500 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 0 for these rout
29510 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ines..**.** ^If
29520 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 the Nth column r
29530 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 eturned by the s
29540 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 tatement is an e
29550 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 xpression or.**
29560 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 subquery and is
29570 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c not a column val
29580 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 ue, then all of
29590 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 these functions
295a0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 return.** NULL.
295b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 ^These routine
295c0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 might also retur
295d0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f n NULL if a memo
295e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
295f0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 ror.** occurs.
29600 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 ^Otherwise, they
29610 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
29620 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 of the attached
29630 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 database, table
29640 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 ,.** or column t
29650 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 hat query result
29660 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 column was extr
29670 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a acted from..**.*
29680 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f * ^As with all o
29690 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 ther SQLite APIs
296a0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 , those whose na
296b0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 mes end with "16
296c0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d " return.** UTF-
296d0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 16 encoded strin
296e0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 gs and the other
296f0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
29700 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e n UTF-8..**.** ^
29710 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f These APIs are o
29720 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
29730 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 the library was
29740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
29750 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
29760 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 ABLE_COLUMN_META
29770 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 DATA] C-preproce
29780 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a ssor symbol..**.
29790 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
297a0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
297b0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 ne or more of th
297c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 ese routines aga
297d0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a inst the same.**
297e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
297f0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 ent and column a
29800 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 t the same time
29810 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
29820 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 are.** undefine
29830 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 d..**.** If two
29840 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 or more threads
29850 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 call one or more
29860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
29870 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
29880 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 e | column metad
29890 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a ata interfaces].
298a0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ** for the same
298b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
298c0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 ent] and result
298d0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 column.** at the
298e0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
298f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
29900 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 undefined..*/.SQ
29910 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
29920 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
29930 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d umn_database_nam
29940 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
29950 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
29960 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c const void *sql
29970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
29980 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 base_name16(sqli
29990 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
299a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
299b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
299c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
299d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
299e0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
299f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
29a00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
29a10 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
29a20 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
29a30 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
29a40 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
29a50 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 n_origin_name(sq
29a60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
29a70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
29a80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
29a90 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e _column_origin_n
29aa0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
29ab0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
29ac0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 CAPI3REF: Decla
29ad0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 red Datatype Of
29ae0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a A Query Result.*
29af0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 *.** ^(The first
29b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
29b10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
29b20 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 ent]..** If this
29b30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 statement is a
29b40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
29b50 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 nt and the Nth c
29b60 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 olumn of the.**
29b70 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 returned result
29b80 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c set of that [SEL
29b90 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 ECT] is a table
29ba0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a column (not an.*
29bb0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 * expression or
29bc0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 subquery) then t
29bd0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 he declared type
29be0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a of the table.**
29bf0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 column is retur
29c00 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 ned.)^ ^If the
29c10 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 Nth column of th
29c20 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 e result set is
29c30 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e an.** expression
29c40 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 or subquery, th
29c50 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 en a NULL pointe
29c60 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
29c70 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 * ^The returned
29c80 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 string is always
29c90 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a UTF-8 encoded..
29ca0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d **.** ^(For exam
29cb0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 ple, given the d
29cc0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a atabase schema:.
29cd0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 **.** CREATE TAB
29ce0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 LE t1(c1 VARIANT
29cf0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 );.**.** and the
29d00 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 following state
29d10 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 ment to be compi
29d20 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 led:.**.** SELEC
29d30 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f T c1 + 1, c1 FRO
29d40 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 M t1;.**.** this
29d50 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 routine would r
29d60 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 eturn the string
29d70 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 "VARIANT" for t
29d80 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 he second result
29d90 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 .** column (i==1
29da0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f ), and a NULL po
29db0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 inter for the fi
29dc0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d rst result colum
29dd0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a n (i==0).)^.**.*
29de0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 * ^SQLite uses d
29df0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 ynamic run-time
29e00 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 typing. ^So jus
29e10 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 t because a colu
29e20 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 mn.** is declare
29e30 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 d to contain a p
29e40 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 articular type d
29e50 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 oes not mean tha
29e60 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 t the.** data st
29e70 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c ored in that col
29e80 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 umn is of the de
29e90 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 clared type. SQ
29ea0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e Lite is.** stron
29eb0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 gly typed, but t
29ec0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e he typing is dyn
29ed0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e amic not static.
29ee0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 ^Type.** is as
29ef0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e sociated with in
29f00 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c dividual values,
29f10 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f not with the co
29f20 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 ntainers.** used
29f30 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 to hold those v
29f40 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 alues..*/.SQLITE
29f50 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
29f60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
29f70 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 decltype(sqlite3
29f80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
29f90 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
29fa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
29fb0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 mn_decltype16(sq
29fc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
29fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
29fe0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 F: Evaluate An S
29ff0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a QL Statement.**.
2a000 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
2a010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2a020 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
2a030 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a d using either.*
2a040 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2a050 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
2a060 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2a070 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 2()] or one of t
2a080 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
2a090 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
2a0a0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b _prepare()] or [
2a0b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2a0c0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 6()], this funct
2a0d0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 ion.** must be c
2a0e0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
2a0f0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 e times to evalu
2a100 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
2a110 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
2a120 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
2a130 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 vior of the sqli
2a140 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 te3_step() inter
2a150 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f face depend.** o
2a160 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 n whether the st
2a170 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 atement was prep
2a180 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e ared using the n
2a190 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 ewer "v2" interf
2a1a0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ace.** [sqlite3_
2a1b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2a1c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
2a1d0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 re16_v2()] or th
2a1e0 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a e older legacy.*
2a1f0 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c * interface [sql
2a200 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2a210 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2a220 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
2a230 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
2a240 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 w "v2" interface
2a250 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
2a260 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
2a270 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
2a280 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
2a290 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
2a2a0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
2a2b0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 **.** ^In the le
2a2c0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2a2d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
2a2e0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 will be either
2a2f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a [SQLITE_BUSY],.*
2a300 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
2a310 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b [SQLITE_ROW], [
2a320 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f SQLITE_ERROR], o
2a330 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 r [SQLITE_MISUSE
2a340 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
2a350 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
2a360 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
2a370 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
2a380 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
2a390 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
2a3a0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
2a3b0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e as well..**.** ^
2a3c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 [SQLITE_BUSY] me
2a3d0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 ans that the dat
2a3e0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 abase engine was
2a3f0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 unable to acqui
2a400 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 re the.** databa
2a410 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 se locks it need
2a420 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e s to do its job.
2a430 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d ^If the statem
2a440 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 ent is a [COMMIT
2a450 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f ].** or occurs o
2a460 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 utside of an exp
2a470 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
2a480 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 n, then you can
2a490 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 retry the.** sta
2a4a0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 tement. If the
2a4b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
2a4c0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 a [COMMIT] and
2a4d0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e occurs within an
2a4e0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 .** explicit tra
2a4f0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f nsaction then yo
2a500 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 u should rollbac
2a510 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
2a520 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 n before.** cont
2a530 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b inuing..**.** ^[
2a540 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
2a550 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
2a560 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
2a570 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
2a580 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
2a590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
2a5a0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
2a5b0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
2a5c0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
2a5d0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
2a5e0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
2a5f0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
2a600 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
2a610 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
2a620 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
2a630 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 state..**.** ^If
2a640 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2a650 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 nt being execute
2a660 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 d returns any da
2a670 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 ta, then [SQLITE
2a680 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 _ROW].** is retu
2a690 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 rned each time a
2a6a0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 new row of data
2a6b0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 is ready for pr
2a6c0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a ocessing by the.
2a6d0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 ** caller. The v
2a6e0 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 alues may be acc
2a6f0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 essed using the
2a700 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
2a710 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 unctions]..** sq
2a720 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 lite3_step() is
2a730 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 called again to
2a740 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 retrieve the nex
2a750 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a t row of data..*
2a760 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 *.** ^[SQLITE_ER
2a770 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
2a780 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
2a790 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
2a7a0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
2a7b0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
2a7c0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
2a7d0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
2a7e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
2a7f0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
2a800 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
2a810 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
2a820 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
2a830 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 rmsg()]..** ^Wit
2a840 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
2a850 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
2a860 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
2a870 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
2a880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
2a890 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
2a8a0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
2a8b0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
2a8c0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
2a8d0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
2a8e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2a8f0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
2a900 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2a910 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 tement]. ^In th
2a920 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2a930 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 ,.** the more sp
2a940 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
2a950 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 e is returned di
2a960 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 rectly by sqlite
2a970 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_step()..**.**
2a980 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2a990 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 means that the t
2a9a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 his routine was
2a9b0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 called inappropr
2a9c0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 iately..** Perha
2a9d0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 ps it was called
2a9e0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
2a9f0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2aa00 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 has.** already b
2aa10 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e een [sqlite3_fin
2aa20 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
2aa30 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 d] or on one tha
2aa40 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 t had.** previou
2aa50 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 sly returned [SQ
2aa60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b LITE_ERROR] or [
2aa70 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f SQLITE_DONE]. O
2aa80 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 r it could.** be
2aa90 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
2aaa0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
2aab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 connection is b
2aac0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f eing used by two
2aad0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 or.** more thre
2aae0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
2aaf0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a moment in time..
2ab00 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 **.** For all ve
2ab10 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2ab20 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 up to and inclu
2ab30 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 ding 3.6.23.1, a
2ab40 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
2ab50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 ite3_reset()] wa
2ab60 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 s required after
2ab70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2ab80 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e returned anythin
2ab90 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 g.** other than
2aba0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 [SQLITE_ROW] bef
2abb0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 ore any subseque
2abc0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 nt invocation of
2abd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
2abe0 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 (). Failure to
2abf0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
2ac00 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
2ac10 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
2ac20 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 reset()] would r
2ac30 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c esult in an [SQL
2ac40 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 ITE_MISUSE] retu
2ac50 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 rn from.** sqlit
2ac60 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 e3_step(). But
2ac70 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e after version 3.
2ac80 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 6.23.1, sqlite3_
2ac90 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 step() began.**
2aca0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
2acb0 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 _reset()] automa
2acc0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 tically in this
2acd0 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 circumstance rat
2ace0 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 her.** than retu
2acf0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 rning [SQLITE_MI
2ad00 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 SUSE]. This is
2ad10 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 not considered a
2ad20 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a compatibility.*
2ad30 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 * break because
2ad40 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 any application
2ad50 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 that ever receiv
2ad60 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 es an SQLITE_MIS
2ad70 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 USE error.** is
2ad80 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 broken by defini
2ad90 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 tion. The [SQLI
2ada0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 TE_OMIT_AUTORESE
2adb0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
2adc0 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 option.** can be
2add0 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 used to restore
2ade0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 the legacy beha
2adf0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 vior..**.** <b>G
2ae00 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 oofy Interface A
2ae10 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 lert:</b> In the
2ae20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
2ae30 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 e, the sqlite3_s
2ae40 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 tep().** API alw
2ae50 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
2ae60 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
2ae70 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
2ae80 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a , following any.
2ae90 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ** error other t
2aea0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
2aeb0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 ] and [SQLITE_MI
2aec0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 SUSE]. You must
2aed0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
2aee0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2aef0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2af00 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 )] in order to f
2af10 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a ind one of the.*
2af20 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f * specific [erro
2af30 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 r codes] that be
2af40 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 tter describes t
2af50 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 he error..** We
2af60 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 admit that this
2af70 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 is a goofy desig
2af80 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 n. The problem
2af90 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a has been fixed.*
2afa0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 * with the "v2"
2afb0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 interface. If y
2afc0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f ou prepare all o
2afd0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 f your SQL state
2afe0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 ments.** using e
2aff0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
2b000 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2b010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2b020 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 16_v2()] instead
2b030 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 .** of the legac
2b040 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
2b050 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
2b060 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
2b070 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 interfaces,.** t
2b080 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 hen the more spe
2b090 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
2b0a0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 es] are returned
2b0b0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 directly.** by
2b0c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
2b0d0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
2b0e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
2b0f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a s recommended..*
2b100 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2b110 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 sqlite3_step(sq
2b120 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
2b130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2b140 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2b150 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 in a result set
2b160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2b170 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2b180 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2b190 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2b1a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
2b1b0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 .** current row
2b1c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2b1d0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 t of [prepared s
2b1e0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
2b1f0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 ^If prepared sta
2b200 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f tement P does no
2b210 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 t have results r
2b220 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a eady to return.*
2b230 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 * (via calls to
2b240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c the [sqlite3_col
2b250 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 umn_int | sqlite
2b260 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 3_column_*()] of
2b270 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 .** interfaces)
2b280 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 then sqlite3_dat
2b290 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 a_count(P) retur
2b2a0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ns 0..** ^The sq
2b2b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2b2c0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f (P) routine also
2b2d0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 returns 0 if P
2b2e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
2b2f0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 r..** ^The sqlit
2b300 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
2b310 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2b320 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 0 if the previo
2b330 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 us call to.** [s
2b340 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 qlite3_step](P)
2b350 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
2b360 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 _DONE]. ^The sq
2b370 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2b380 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 (P).** will retu
2b390 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 rn non-zero if p
2b3a0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
2b3b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 [sqlite3_step](P
2b3c0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 ) returned.** [S
2b3d0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 QLITE_ROW], exce
2b3e0 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f pt in the case o
2b3f0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e f the [PRAGMA in
2b400 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d cremental_vacuum
2b410 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c ].** where it al
2b420 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 ways returns zer
2b430 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 o since each ste
2b440 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d p of that multi-
2b450 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 step.** pragma r
2b460 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 eturns 0 columns
2b470 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
2b480 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
2b490 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
2b4a0 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )].*/.SQLITE_API
2b4b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 int sqlite3_dat
2b4c0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f a_count(sqlite3_
2b4d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
2b4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
2b4f0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 undamental Datat
2b500 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ypes.** KEYWORDS
2b510 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a : SQLITE_TEXT.**
2b520 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 .** ^(Every valu
2b530 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 e in SQLite has
2b540 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 one of five fund
2b550 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 amental datatype
2b560 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
2b570 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 <li> 64-bit sig
2b580 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c ned integer.** <
2b590 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 li> 64-bit IEEE
2b5a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e floating point n
2b5b0 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 umber.** <li> st
2b5c0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f ring.** <li> BLO
2b5d0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a B.** <li> NULL.*
2b5e0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
2b5f0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
2b600 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 are codes for ea
2b610 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 ch of those type
2b620 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 s..**.** Note th
2b630 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 at the SQLITE_TE
2b640 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 XT constant was
2b650 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c also used in SQL
2b660 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a ite version 2.**
2b670 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c for a completel
2b680 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e y different mean
2b690 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 ing. Software t
2b6a0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 hat links agains
2b6b0 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 t both.** SQLite
2b6c0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 version 2 and S
2b6d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 QLite version 3
2b6e0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 should use SQLIT
2b6f0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 E3_TEXT, not.**
2b700 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a SQLITE_TEXT..*/.
2b710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
2b720 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e NTEGER 1.#defin
2b730 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 e SQLITE_FLOAT
2b740 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
2b750 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 TE_BLOB 4.#d
2b760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c efine SQLITE_NUL
2b770 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 L 5.#ifdef S
2b780 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 QLITE_TEXT.# und
2b790 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 ef SQLITE_TEXT.#
2b7a0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 else.# define SQ
2b7b0 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a LITE_TEXT 3.
2b7c0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 #endif.#define S
2b7d0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 QLITE3_TEXT
2b7e0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 3../*.** CAPI3RE
2b7f0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 F: Result Values
2b800 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a From A Query.**
2b810 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 KEYWORDS: {colu
2b820 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
2b830 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ons}.**.** These
2b840 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 routines form t
2b850 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 he "result set"
2b860 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
2b870 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2b880 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2b890 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 ion about a sing
2b8a0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 le column of the
2b8b0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 current.** resu
2b8c0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 lt row of a quer
2b8d0 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 y. ^In every ca
2b8e0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 se the first arg
2b8f0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
2b900 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 er.** to the [pr
2b910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b920 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 ] that is being
2b930 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b evaluated (the [
2b940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a sqlite3_stmt*].*
2b950 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 * that was retur
2b960 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
2b970 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2b980 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 or one of its va
2b990 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 riants).** and t
2b9a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
2b9b0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 nt is the index
2b9c0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f of the column fo
2b9d0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 r which informat
2b9e0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 ion.** should be
2b9f0 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 returned. ^The
2ba00 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 leftmost column
2ba10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2ba20 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 t has the index
2ba30 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 0..** ^The numbe
2ba40 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
2ba50 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 the result can b
2ba60 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 e determined usi
2ba70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 ng.** [sqlite3_c
2ba80 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a olumn_count()]..
2ba90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c **.** If the SQL
2baa0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 statement does
2bab0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f not currently po
2bac0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 int to a valid r
2bad0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a ow, or if the.**
2bae0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 column index is
2baf0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 out of range, t
2bb00 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 he result is und
2bb10 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 efined..** These
2bb20 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e routines may on
2bb30 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 ly be called whe
2bb40 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e n the most recen
2bb50 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 t call to.** [sq
2bb60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
2bb70 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 s returned [SQLI
2bb80 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 TE_ROW] and neit
2bb90 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f her.** [sqlite3_
2bba0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 reset()] nor [sq
2bbb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
2bbc0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c ] have been call
2bbd0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e ed subsequently.
2bbe0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 .** If any of th
2bbf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
2bc00 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 called after [s
2bc10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2bc20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 or.** [sqlite3_f
2bc30 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 inalize()] or af
2bc40 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ter [sqlite3_ste
2bc50 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
2bc60 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f d.** something o
2bc70 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
2bc80 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 E_ROW], the resu
2bc90 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
2bca0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 d..** If [sqlite
2bcb0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 3_step()] or [sq
2bcc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f lite3_reset()] o
2bcd0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2bce0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 ize()].** are ca
2bcf0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 lled from a diff
2bd00 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 erent thread whi
2bd10 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 le any of these
2bd20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 routines.** are
2bd30 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 pending, then th
2bd40 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
2bd50 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
2bd60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
2bd70 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e mn_type() routin
2bd80 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a e returns the.**
2bd90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
2bda0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 | datatype code
2bdb0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 ] for the initia
2bdc0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f l data type.** o
2bdd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c f the result col
2bde0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 umn. ^The retur
2bdf0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 ned value is one
2be00 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 of [SQLITE_INTE
2be10 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 GER],.** [SQLITE
2be20 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 _FLOAT], [SQLITE
2be30 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f _TEXT], [SQLITE_
2be40 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 BLOB], or [SQLIT
2be50 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 E_NULL]. The va
2be60 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lue.** returned
2be70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
2be80 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 n_type() is only
2be90 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e meaningful if n
2bea0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 o type.** conver
2beb0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 sions have occur
2bec0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 red as described
2bed0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 below. After a
2bee0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
2bef0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 ,.** the value r
2bf00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2bf10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
2bf20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 is undefined.
2bf30 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f Future.** versio
2bf40 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 ns of SQLite may
2bf50 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 change the beha
2bf60 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f vior of sqlite3_
2bf70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a column_type().**
2bf80 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 following a typ
2bf90 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a e conversion..**
2bfa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2bfb0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2bfc0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 UTF-8 string the
2bfd0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f n the sqlite3_co
2bfe0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 lumn_bytes().**
2bff0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2c000 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
2c010 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 tes in that BLOB
2c020 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e or string..** ^
2c030 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
2c040 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 a UTF-16 string
2c050 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2c060 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f olumn_bytes() co
2c070 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 nverts.** the st
2c080 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e ring to UTF-8 an
2c090 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
2c0a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
2c0b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 es..** ^If the r
2c0c0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
2c0d0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
2c0e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2c0f0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 es() uses.** [sq
2c100 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
2c110 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 ] to convert tha
2c120 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 t value to a UTF
2c130 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 -8 string and re
2c140 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d turns.** the num
2c150 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
2c160 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 that string..**
2c170 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2c180 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c s NULL, then sql
2c190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2c1a0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f s() returns zero
2c1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2c1c0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 result is a BLOB
2c1d0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e or UTF-16 strin
2c1e0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
2c1f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2c200 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 6().** routine r
2c210 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
2c220 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2c230 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
2c240 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
2c250 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 sult is a UTF-8
2c260 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c string, then sql
2c270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2c280 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a s16() converts.*
2c290 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 * the string to
2c2a0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 UTF-16 and then
2c2b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
2c2c0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 er of bytes..**
2c2d0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2c2e0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 s a numeric valu
2c2f0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 e then sqlite3_c
2c300 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2c310 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 uses.** [sqlite3
2c320 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 _snprintf()] to
2c330 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c convert that val
2c340 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 ue to a UTF-16 s
2c350 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2c360 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2c370 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2c380 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2c390 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2c3a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2c3b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2c3c0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
2c3d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 **.** ^The value
2c3e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 s returned by [s
2c3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2c400 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b tes()] and .** [
2c410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c420 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 ytes16()] do not
2c430 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 include the zer
2c440 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 o terminators at
2c450 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 the end.** of t
2c460 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 he string. ^For
2c470 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 clarity: the va
2c480 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
2c490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2c4a0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 umn_bytes()] and
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2c4c0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 _bytes16()] are
2c4d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
2c4e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 bytes in the st
2c4f0 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 ring, not the nu
2c500 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
2c510 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e rs..**.** ^Strin
2c520 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 gs returned by s
2c530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2c540 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 xt() and sqlite3
2c550 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2c560 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 ,.** even empty
2c570 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 strings, are alw
2c580 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 ays zero-termina
2c590 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ted. ^The retur
2c5a0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 n.** value from
2c5b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2c5c0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f lob() for a zero
2c5d0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 -length BLOB is
2c5e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
2c5f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 **.** ^The objec
2c600 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 t returned by [s
2c610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2c620 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 lue()] is an.**
2c630 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c [unprotected sql
2c640 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 ite3_value] obje
2c650 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 ct. An unprotec
2c660 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2c670 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 e object.** may
2c680 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
2c690 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f h [sqlite3_bind_
2c6a0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 value()] and [sq
2c6b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
2c6c0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 ue()]..** If the
2c6d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
2c6e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
2c6f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a ect returned by.
2c700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
2c710 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 mn_value()] is u
2c720 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 sed in any other
2c730 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 way, including
2c740 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 calls.** to rout
2c750 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 ines like [sqlit
2c760 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c e3_value_int()],
2c770 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2c780 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
2c790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 sqlite3_value_by
2c7a0 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 tes()], then the
2c7b0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2c7c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 efined..**.** Th
2c7d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 ese routines att
2c7e0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 empt to convert
2c7f0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 the value where
2c800 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 appropriate. ^F
2c810 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 or.** example, i
2c820 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 f the internal r
2c830 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 epresentation is
2c840 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 FLOAT and a tex
2c850 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 t result.** is r
2c860 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 equested, [sqlit
2c870 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 e3_snprintf()] i
2c880 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c s used internall
2c890 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 y to perform the
2c8a0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 .** conversion a
2c8b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e utomatically. ^
2c8c0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 (The following t
2c8d0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 able details the
2c8e0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 conversions.**
2c8f0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 that are applied
2c900 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
2c910 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 ote>.** <table b
2c920 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 order="1">.** <t
2c930 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c r><th> Internal<
2c940 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 br>Type <th> Req
2c950 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c uested<br>Type <
2c960 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a th> Conversion.
2c970 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 **.** <tr><td>
2c980 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 NULL <td> INT
2c990 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 EGER <td> Resu
2c9a0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c lt is 0.** <tr><
2c9b0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
2c9c0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2c9d0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a Result is 0.0.*
2c9e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2c9f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
2ca00 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2ca10 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
2ca20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2ca30 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
2ca40 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2ca50 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a s NULL pointer.*
2ca60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2ca70 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
2ca80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2ca90 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
2caa0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2cab0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2cac0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
2cad0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
2cae0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
2caf0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2cb00 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
2cb10 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
2cb20 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
2cb30 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2cb40 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2cb50 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 <td> Convert fr
2cb60 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 om float to inte
2cb70 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ger.** <tr><td>
2cb80 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 FLOAT <td>
2cb90 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 TEXT <td> ASC
2cba0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 II rendering of
2cbb0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 the float.** <tr
2cbc0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
2cbd0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 td> BLOB <t
2cbe0 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 d> Same as FLOAT
2cbf0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 ->TEXT.** <tr><t
2cc00 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e d> TEXT <td>
2cc10 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
2cc20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 Use atoi().** <t
2cc30 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
2cc40 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2cc50 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a td> Use atof().*
2cc60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2cc70 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
2cc80 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 <td> No chang
2cc90 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 e.** <tr><td> B
2cca0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOB <td> INTE
2ccb0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 GER <td> Conve
2ccc0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 rt to TEXT then
2ccd0 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 use atoi().** <t
2cce0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 r><td> BLOB
2ccf0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
2cd00 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 td> Convert to T
2cd10 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f EXT then use ato
2cd20 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 f().** <tr><td>
2cd30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
2cd40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
2cd50 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
2cd60 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
2cd70 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
2cd80 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
2cd90 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 * The table abov
2cda0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 e makes referenc
2cdb0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 e to standard C
2cdc0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e library function
2cdd0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 s atoi().** and
2cde0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 atof(). SQLite
2cdf0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 does not really
2ce00 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 use these functi
2ce10 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 ons. It has its
2ce20 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 .** own equivale
2ce30 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 nt internal rout
2ce40 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 ines. The atoi(
2ce50 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d ) and atof() nam
2ce60 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 es are.** used i
2ce70 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 n the table for
2ce80 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 brevity and beca
2ce90 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d use they are fam
2cea0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a iliar to most.**
2ceb0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a C programmers..
2cec0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2ced0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 when type conver
2cee0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 sions occur, poi
2cef0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 nters returned b
2cf00 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 y prior.** calls
2cf10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2cf20 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 mn_blob(), sqlit
2cf30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2cf40 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 , and/or.** sqli
2cf50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2cf60 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 6() may be inval
2cf70 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 idated..** Type
2cf80 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 conversions and
2cf90 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 pointer invalida
2cfa0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 tions might occu
2cfb0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c r.** in the foll
2cfc0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a owing cases:.**.
2cfd0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
2cfe0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2cff0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e ent is a BLOB an
2d000 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2d010 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 _text() or.**
2d020 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d sqlite3_colum
2d030 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 n_text16() is ca
2d040 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 lled. A zero-te
2d050 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a rminator might.*
2d060 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 * need to b
2d070 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 e added to the s
2d080 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c tring.</li>.** <
2d090 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2d0a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 content is UTF-8
2d0b0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 text and sqlite
2d0c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
2d0d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2d0e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2d0f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2d100 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 The content mu
2d110 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a st be converted.
2d120 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 ** to UTF-1
2d130 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 6.</li>.** <li>
2d140 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
2d150 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 ent is UTF-16 te
2d160 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
2d170 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 olumn_bytes() or
2d180 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2d190 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 _column_text() i
2d1a0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 s called. The c
2d1b0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 ontent must be c
2d1c0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 onverted.**
2d1d0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a to UTF-8.</li>.
2d1e0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e ** </ul>.**.** ^
2d1f0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 Conversions betw
2d200 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 een UTF-16be and
2d210 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c UTF-16le are al
2d220 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 ways done in pla
2d230 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 ce and do.** not
2d240 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 invalidate a pr
2d250 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f ior pointer, tho
2d260 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 ugh of course th
2d270 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2d280 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
2d290 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 the prior pointe
2d2a0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c r references wil
2d2b0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 l have been modi
2d2c0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e fied. Other kin
2d2d0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 ds.** of convers
2d2e0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 ion are done in
2d2f0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 place when it is
2d300 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 possible, but s
2d310 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a ometimes they.**
2d320 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c are not possibl
2d330 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 e and in those c
2d340 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 ases prior point
2d350 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 ers are invalida
2d360 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ted..**.** The s
2d370 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 afest and easies
2d380 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f t to remember po
2d390 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b licy is to invok
2d3a0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 e these routines
2d3b0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 .** in one of th
2d3c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 e following ways
2d3d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
2d3e0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
2d3f0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f umn_text() follo
2d400 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
2d410 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
2d420 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
2d430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
2d440 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
2d450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2d460 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
2d470 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
2d480 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 text16() followe
2d490 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c d by sqlite3_col
2d4a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c umn_bytes16()</l
2d4b0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a i>.** </ul>.**.*
2d4c0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
2d4d0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c , you should cal
2d4e0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e l sqlite3_column
2d4f0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 _text(),.** sqli
2d500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2d510 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f ), or sqlite3_co
2d520 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 lumn_text16() fi
2d530 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 rst to force the
2d540 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 result.** into
2d550 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d the desired form
2d560 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 at, then invoke
2d570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2d580 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c ytes() or.** sql
2d590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2d5a0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 s16() to find th
2d5b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 e size of the re
2d5c0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 sult. Do not mi
2d5d0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 x calls.** to sq
2d5e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2d5f0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 t() or sqlite3_c
2d600 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 olumn_blob() wit
2d610 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 h calls to.** sq
2d620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2d630 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e es16(), and do n
2d640 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 ot mix calls to
2d650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2d660 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 ext16().** with
2d670 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
2d680 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e _column_bytes().
2d690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e .**.** ^The poin
2d6a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 ters returned ar
2d6b0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 e valid until a
2d6c0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 type conversion
2d6d0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 occurs as.** des
2d6e0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 cribed above, or
2d6f0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f until [sqlite3_
2d700 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
2d710 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
2d720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
2d730 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 lize()] is calle
2d740 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 d. ^The memory
2d750 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f space used to ho
2d760 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e ld strings.** an
2d770 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 d BLOBs is freed
2d780 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 automatically.
2d790 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 Do <b>not</b> p
2d7a0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 ass the pointers
2d7b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 returned.** [sq
2d7c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2d7d0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
2d7e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
2d7f0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
2d800 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
2d810 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
2d820 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2d830 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2d840 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
2d850 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
2d860 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
2d870 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
2d880 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
2d890 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
2d8a0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
2d8b0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
2d8c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2d8d0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
2d8e0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
2d8f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
2d900 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
2d910 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
2d920 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
2d930 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 MEM].)^.*/.SQLIT
2d940 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 E_API const void
2d950 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
2d960 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 _blob(sqlite3_st
2d970 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2d980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2d990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
2d9a0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tes(sqlite3_stmt
2d9b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
2d9c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2d9d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2d9e0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 s16(sqlite3_stmt
2d9f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
2da00 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 LITE_API double
2da10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
2da20 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 ouble(sqlite3_st
2da30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
2da40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2da50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e qlite3_column_in
2da60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2da70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
2da80 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
2da90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c nt64 sqlite3_col
2daa0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 umn_int64(sqlite
2dab0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2dac0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 l);.SQLITE_API c
2dad0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
2dae0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2daf0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f mn_text(sqlite3_
2db00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2db10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2db20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
2db30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 _column_text16(s
2db40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2db50 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
2db60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2db70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 column_type(sqli
2db80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
2db90 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
2dba0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a sqlite3_value *
2dbb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2dbc0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d alue(sqlite3_stm
2dbd0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a t*, int iCol);..
2dbe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2dbf0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 Destroy A Prepar
2dc00 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
2dc10 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ect.**.** ^The s
2dc20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2dc30 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
2dc40 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 lled to delete a
2dc50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2dc60 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 ment]..** ^If th
2dc70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 e most recent ev
2dc80 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 aluation of the
2dc90 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e statement encoun
2dca0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a tered no errors.
2dcb0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 ** or if the sta
2dcc0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 tement is never
2dcd0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 been evaluated,
2dce0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e then sqlite3_fin
2dcf0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a alize() returns.
2dd00 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e ** SQLITE_OK. ^
2dd10 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2dd20 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 nt evaluation of
2dd30 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 statement S fai
2dd40 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c led, then.** sql
2dd50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 ite3_finalize(S)
2dd60 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 returns the app
2dd70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 ropriate [error
2dd80 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 code] or.** [ext
2dd90 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 ended error code
2dda0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
2ddb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 lite3_finalize(S
2ddc0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 ) routine can be
2ddd0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 called at any p
2dde0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 oint during.** t
2ddf0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 he life cycle of
2de00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2de10 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f ment] S:.** befo
2de20 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 re statement S i
2de30 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 s ever evaluated
2de40 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f , after.** one o
2de50 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 r more calls to
2de60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2de70 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 ], or after any
2de80 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 call.** to [sqli
2de90 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 te3_step()] rega
2dea0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
2deb0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 r or not the sta
2dec0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f tement has.** co
2ded0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f mpleted executio
2dee0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 n..**.** ^Invoki
2def0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c ng sqlite3_final
2df00 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 ize() on a NULL
2df10 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 pointer is a har
2df20 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a mless no-op..**.
2df30 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
2df40 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 on must finalize
2df50 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 every [prepared
2df60 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f statement] in o
2df70 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a rder to avoid.**
2df80 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e resource leaks.
2df90 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f It is a grievo
2dfa0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 us error for the
2dfb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
2dfc0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 try to use.** a
2dfd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2dfe0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 nt after it has
2dff0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 been finalized.
2e000 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 Any use of a pr
2e010 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
2e020 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 ent after it has
2e030 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 been finalized
2e040 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e can result in un
2e050 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 defined and.** u
2e060 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 ndesirable behav
2e070 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 ior such as segf
2e080 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 aults and heap c
2e090 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 orruption..*/.SQ
2e0a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2e0b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 ite3_finalize(sq
2e0c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2e0d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2e0e0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 REF: Reset A Pre
2e0f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
2e100 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 Object.**.** The
2e110 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 sqlite3_reset()
2e120 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
2e130 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b led to reset a [
2e140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e150 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 nt].** object ba
2e160 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2e170 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 l state, ready t
2e180 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 o be re-executed
2e190 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 ..** ^Any SQL st
2e1a0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
2e1b0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
2e1c0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
2e1d0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
2e1e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2e1f0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
2e200 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
2e210 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
2e220 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
2e230 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
2e240 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
2e250 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ings..**.** ^The
2e260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2e270 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
2e280 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
2e290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
2e2a0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 ** back to the b
2e2b0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 eginning of its
2e2c0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e program..**.** ^
2e2d0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
2e2e0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
2e2f0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
2e300 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2e310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
2e320 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
2e330 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROW] or [SQLITE_
2e340 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 DONE],.** or if
2e350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2e360 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
2e370 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
2e380 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 n S,.** then [sq
2e390 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
2e3a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
2e3b0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 OK]..**.** ^If t
2e3c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
2e3d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2e3e0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
2e3f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
2e400 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
2e410 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
2e420 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hen.** [sqlite3_
2e430 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
2e440 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 s an appropriate
2e450 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
2e460 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
2e470 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 e3_reset(S)] int
2e480 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 erface does not
2e490 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
2e4a0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c s.** of any [sql
2e4b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 ite3_bind_blob|b
2e4c0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 indings] on the
2e4d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e4e0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 ent] S..*/.SQLIT
2e4f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2e500 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 3_reset(sqlite3_
2e510 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
2e520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
2e530 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e reate Or Redefin
2e540 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a e SQL Functions.
2e550 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 ** KEYWORDS: {fu
2e560 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
2e570 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 routines}.** KEY
2e580 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 WORDS: {applicat
2e590 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2e5a0 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 function}.** KEY
2e5b0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 WORDS: {applicat
2e5c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2e5d0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a functions}.**.**
2e5e0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e ^These function
2e5f0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 s (collectively
2e600 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 known as "functi
2e610 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
2e620 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 ines").** are us
2e630 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 ed to add SQL fu
2e640 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 nctions or aggre
2e650 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 gates or to rede
2e660 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f fine the behavio
2e670 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 r.** of existing
2e680 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f SQL functions o
2e690 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 r aggregates. T
2e6a0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e he only differen
2e6b0 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 ces between.** t
2e6c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
2e6d0 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 e the text encod
2e6e0 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 ing expected for
2e6f0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 .** the second p
2e700 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 arameter (the na
2e710 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 me of the functi
2e720 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 on being created
2e730 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 ).** and the pre
2e740 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 sence or absence
2e750 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 of a destructor
2e760 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a callback for.**
2e770 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
2e780 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a data pointer..*
2e790 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2e7a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2e7b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
2e7c0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 ction] to which
2e7d0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 the SQL.** funct
2e7e0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 ion is to be add
2e7f0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c ed. ^If an appl
2e800 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 ication uses mor
2e810 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 e than one datab
2e820 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
2e830 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 n then applicati
2e840 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2e850 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 unctions must be
2e860 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 added.** to eac
2e870 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
2e880 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 ction separately
2e890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 ..**.** ^The sec
2e8a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
2e8b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
2e8c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f SQL function to
2e8d0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a be created or.*
2e8e0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 * redefined. ^T
2e8f0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
2e900 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 name is limited
2e910 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e to 255 bytes in
2e920 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 a UTF-8.** repr
2e930 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c esentation, excl
2e940 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 usive of the zer
2e950 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e o-terminator. ^
2e960 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 Note that the na
2e970 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d me.** length lim
2e980 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 it is in UTF-8 b
2e990 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 ytes, not charac
2e9a0 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 ters nor UTF-16
2e9b0 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 bytes. .** ^Any
2e9c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 attempt to crea
2e9d0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 te a function wi
2e9e0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 th a longer name
2e9f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 .** will result
2ea00 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 in [SQLITE_MISUS
2ea10 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 E] being returne
2ea20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 d..**.** ^The th
2ea30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e ird parameter (n
2ea40 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e Arg).** is the n
2ea50 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e umber of argumen
2ea60 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 ts that the SQL
2ea70 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 function or.** a
2ea80 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 ggregate takes.
2ea90 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 ^If this paramet
2eaa0 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 er is -1, then t
2eab0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
2eac0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 or.** aggregate
2ead0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d may take any num
2eae0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 ber of arguments
2eaf0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
2eb00 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 he limit.** set
2eb10 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 by [sqlite3_limi
2eb20 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 t]([SQLITE_LIMIT
2eb30 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e _FUNCTION_ARG]).
2eb40 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a If the third.*
2eb50 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c * parameter is l
2eb60 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 ess than -1 or g
2eb70 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 reater than 127
2eb80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
2eb90 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 r is.** undefine
2eba0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f d..**.** ^The fo
2ebb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 urth parameter,
2ebc0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 eTextRep, specif
2ebd0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c ies what.** [SQL
2ebe0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 ITE_UTF8 | text
2ebf0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 encoding] this S
2ec00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 QL function pref
2ec10 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 ers for.** its p
2ec20 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 arameters. Ever
2ec30 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 y SQL function i
2ec40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 mplementation mu
2ec50 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f st be able to wo
2ec60 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 rk.** with UTF-8
2ec70 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 , UTF-16le, or U
2ec80 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f TF-16be. But so
2ec90 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f me implementatio
2eca0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 ns may be.** mor
2ecb0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 e efficient with
2ecc0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 one encoding th
2ecd0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e an another. ^An
2ece0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 application may
2ecf0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 .** invoke sqlit
2ed00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2ed10 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f on() or sqlite3_
2ed20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
2ed30 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6() multiple.**
2ed40 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 times with the s
2ed50 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 ame function but
2ed60 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 with different
2ed70 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 values of eTextR
2ed80 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c ep..** ^When mul
2ed90 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 tiple implementa
2eda0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
2edb0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 e function are a
2edc0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 vailable, SQLite
2edd0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 .** will pick th
2ede0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c e one that invol
2edf0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d ves the least am
2ee00 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e ount of data con
2ee10 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 version..** If t
2ee20 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 here is only a s
2ee30 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 ingle implementa
2ee40 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 tion which does
2ee50 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 not care what te
2ee60 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 xt.** encoding i
2ee70 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 s used, then the
2ee80 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
2ee90 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 should be [SQLI
2eea0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e TE_ANY]..**.** ^
2eeb0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d (The fifth param
2eec0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 eter is an arbit
2eed0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 rary pointer. T
2eee0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
2eef0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 n of the.** func
2ef00 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 tion can gain ac
2ef10 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 cess to this poi
2ef20 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 nter using [sqli
2ef30 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d te3_user_data()]
2ef40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
2ef50 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e ixth, seventh an
2ef60 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 d eighth paramet
2ef70 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 ers, xFunc, xSte
2ef80 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 p and xFinal, ar
2ef90 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f e.** pointers to
2efa0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 C-language func
2efb0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 tions that imple
2efc0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e ment the SQL fun
2efd0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
2efe0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 egate. ^A scalar
2eff0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
2f000 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
2f010 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 entation of the
2f020 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 xFunc.** callbac
2f030 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 k only; NULL poi
2f040 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 nters must be pa
2f050 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 ssed as the xSte
2f060 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 p and xFinal.**
2f070 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 parameters. ^An
2f080 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 aggregate SQL fu
2f090 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
2f0a0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
2f0b0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e n of xStep.** an
2f0c0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c d xFinal and NUL
2f0d0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 L pointer must b
2f0e0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 e passed for xFu
2f0f0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 nc. ^To delete a
2f100 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 n existing.** SQ
2f110 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 L function or ag
2f120 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 gregate, pass NU
2f130 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 LL pointers for
2f140 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 all three functi
2f150 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e on.** callbacks.
2f160 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 .**.** ^(If the
2f170 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 ninth parameter
2f180 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 to sqlite3_creat
2f190 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 e_function_v2()
2f1a0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 is not NULL,.**
2f1b0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 then it is destr
2f1c0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 uctor for the ap
2f1d0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 plication data p
2f1e0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 ointer. .** The
2f1f0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e destructor is in
2f200 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 voked when the f
2f210 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 unction is delet
2f220 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 ed, either by be
2f230 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 ing.** overloade
2f240 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 d or when the da
2f250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2f260 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e n closes.)^.** ^
2f270 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
2f280 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 s also invoked i
2f290 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a f the call to.**
2f2a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
2f2b0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 function_v2() fa
2f2c0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 ils..** ^When th
2f2d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c e destructor cal
2f2e0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e lback of the ten
2f2f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
2f300 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 invoked, it.** i
2f310 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c s passed a singl
2f320 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
2f330 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 is a copy of th
2f340 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
2f350 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 ta .** pointer w
2f360 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 hich was the fif
2f370 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
2f380 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2f390 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a unction_v2()..**
2f3a0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 .** ^It is permi
2f3b0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 tted to register
2f3c0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d multiple implem
2f3d0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 entations of the
2f3e0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f same.** functio
2f3f0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 ns with the same
2f400 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 name but with e
2f410 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 ither differing
2f420 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 numbers of.** ar
2f430 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 guments or diffe
2f440 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 ring preferred t
2f450 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 ext encodings.
2f460 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 ^SQLite will use
2f470 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e .** the implemen
2f480 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 tation that most
2f490 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 closely matches
2f4a0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 the way in whic
2f4b0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e h the.** SQL fun
2f4c0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 ction is used.
2f4d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c ^A function impl
2f4e0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 ementation with
2f4f0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a a non-negative.*
2f500 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 * nArg parameter
2f510 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 is a better mat
2f520 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 ch than a functi
2f530 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
2f540 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 n with.** a nega
2f550 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 tive nArg. ^A f
2f560 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
2f570 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 e preferred text
2f580 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 encoding.** mat
2f590 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 ches the databas
2f5a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 e encoding is a
2f5b0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 better.** match
2f5c0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
2f5d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
2f5e0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e ng is different.
2f5f0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f .** ^A functio
2f600 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
2f610 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
2f620 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 is between UTF16
2f630 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a le and UTF16be.*
2f640 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 * is a closer ma
2f650 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 tch than a funct
2f660 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e ion where the en
2f670 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 coding differenc
2f680 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 e is.** between
2f690 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a UTF8 and UTF16..
2f6a0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 **.** ^Built-in
2f6b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 functions may be
2f6c0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e overloaded by n
2f6d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 ew application-d
2f6e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 efined functions
2f6f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c ..**.** ^An appl
2f700 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
2f710 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d function is perm
2f720 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 itted to call ot
2f730 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e her.** SQLite in
2f740 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 terfaces. Howev
2f750 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d er, such calls m
2f760 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 ust not.** close
2f770 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2f780 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e nnection nor fin
2f790 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 alize or reset t
2f7a0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 he prepared.** s
2f7b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 tatement in whic
2f7c0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 h the function i
2f7d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 s running..*/.SQ
2f7e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2f7f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
2f800 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 tion(. sqlite3
2f810 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 *db,. const cha
2f820 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 r *zFunctionName
2f830 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
2f840 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
2f850 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
2f860 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
2f870 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2f880 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2f890 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
2f8a0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
2f8b0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
2f8c0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
2f8d0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
2f8e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
2f8f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2f900 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
2f910 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 nction16(. sqli
2f920 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
2f930 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e void *zFunction
2f940 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
2f950 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
2f960 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
2f970 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
2f980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
2f990 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
2f9a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
2f9b0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
2f9c0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
2f9d0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
2f9e0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
2f9f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
2fa00 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
2fa10 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
2fa20 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 e_function_v2(.
2fa30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
2fa40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
2fa50 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
2fa60 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
2fa70 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
2fa80 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
2fa90 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
2faa0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
2fab0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
2fac0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
2fad0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
2fae0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
2faf0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
2fb00 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
2fb10 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 ext*),. void(*x
2fb20 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a Destroy)(void*).
2fb30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2fb40 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e EF: Text Encodin
2fb50 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 gs.**.** These c
2fb60 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 onstant define i
2fb70 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 nteger codes tha
2fb80 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 t represent the
2fb90 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 various.** text
2fba0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 encodings suppor
2fbb0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a ted by SQLite..*
2fbc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2fbd0 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 _UTF8
2fbe0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
2fbf0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 _UTF16LE
2fc00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
2fc10 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 _UTF16BE
2fc20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
2fc30 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 _UTF16
2fc40 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 4 /* Use nati
2fc50 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f ve byte order */
2fc60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2fc70 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 ANY 5
2fc80 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 /* sqlite3_c
2fc90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f reate_function o
2fca0 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
2fcb0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
2fcc0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c NED 8 /* sql
2fcd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
2fce0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f ation only */../
2fcf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2fd00 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 eprecated Functi
2fd10 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 ons.** DEPRECATE
2fd20 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 D.**.** These fu
2fd30 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 nctions are [dep
2fd40 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 recated]. In or
2fd50 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a der to maintain.
2fd60 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d ** backwards com
2fd70 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 patibility with
2fd80 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 older code, thes
2fd90 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 e functions cont
2fda0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 inue .** to be s
2fdb0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 upported. Howev
2fdc0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 er, new applicat
2fdd0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 ions should avoi
2fde0 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 d.** the use of
2fdf0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e these functions.
2fe00 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 To help encour
2fe10 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 age people to av
2fe20 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 oid.** using the
2fe30 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 se functions, we
2fe40 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 are not going t
2fe50 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 o tell you what
2fe60 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e they do..*/.#ifn
2fe70 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
2fe80 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 DEPRECATED.SQLIT
2fe90 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
2fea0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
2feb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
2fec0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
2fed0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
2fee0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
2fef0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
2ff00 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f expired(sqlite3_
2ff10 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 stmt*);.SQLITE_A
2ff20 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
2ff30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
2ff40 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e _transfer_bindin
2ff50 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
2ff60 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 , sqlite3_stmt*)
2ff70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
2ff80 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
2ff90 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 nt sqlite3_globa
2ffa0 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b l_recover(void);
2ffb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
2ffc0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f TE_DEPRECATED vo
2ffd0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 id sqlite3_threa
2ffe0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b d_cleanup(void);
2fff0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
30000 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
30010 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 t sqlite3_memory
30020 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
30030 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
30040 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 64,int),void*,sq
30050 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
30060 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
30070 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
30080 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 SQL Function Par
30090 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a ameter Values.**
300a0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 .** The C-langua
300b0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ge implementatio
300c0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f n of SQL functio
300d0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
300e0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 s uses.** this s
300f0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 et of interface
30100 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 routines to acce
30110 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ss the parameter
30120 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 values on.** th
30130 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 e function or ag
30140 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 gregate..**.** T
30150 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 he xFunc (for sc
30160 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 alar functions)
30170 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 or xStep (for ag
30180 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 gregates) parame
30190 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ters.** to [sqli
301a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
301b0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
301c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
301d0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 ion16()].** defi
301e0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 ne callbacks tha
301f0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
30200 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
30210 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a d aggregates..**
30220 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 The 3rd paramet
30230 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c er to these call
30240 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 backs is an arra
30250 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
30260 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 .** [protected s
30270 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
30280 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 jects. There is
30290 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 one [sqlite3_va
302a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a lue] object for.
302b0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 ** each paramete
302c0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e r to the SQL fun
302d0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f ction. These ro
302e0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
302f0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 to.** extract va
30300 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 lues from the [s
30310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
30320 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 jects..**.** The
30330 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
30340 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 only with [prot
30350 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
30360 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
30370 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
30380 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e use these routin
30390 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 es on an [unprot
303a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
303b0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 lue].** object r
303c0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
303d0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
303e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
303f0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
30400 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
30410 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 ding [column acc
30420 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a ess functions].*
30430 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 * except that t
30440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 hese routines ta
30450 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f ke a single [pro
30460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
30470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 alue] object.**
30480 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 pointer instead
30490 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 of a [sqlite3_st
304a0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 mt*] pointer and
304b0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 an integer colu
304c0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a mn number..**.**
304d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
304e0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 lue_text16() int
304f0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 erface extracts
30500 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a a UTF-16 string.
30510 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 ** in the native
30520 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 byte-order of t
30530 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e he host machine.
30540 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
30550 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
30560 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 () and sqlite3_v
30570 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 alue_text16le()
30580 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 interfaces.** ex
30590 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 tract UTF-16 str
305a0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 ings as big-endi
305b0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e an and little-en
305c0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c dian respectivel
305d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 y..**.** ^(The s
305e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d qlite3_value_num
305f0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 eric_type() inte
30600 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 rface attempts t
30610 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 o apply.** numer
30620 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 ic affinity to t
30630 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 he value. This
30640 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 means that an at
30650 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 tempt is.** made
30660 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
30670 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 value to an inte
30680 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 ger or floating
30690 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 point. If.** su
306a0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ch a conversion
306b0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 is possible with
306c0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f out loss of info
306d0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 rmation (in othe
306e0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 r.** words, if t
306f0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 he value is a st
30700 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 ring that looks
30710 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a like a number).*
30720 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 * then the conve
30730 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d rsion is perform
30740 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e ed. Otherwise n
30750 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 o conversion occ
30760 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c urs..** The [SQL
30770 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 ITE_INTEGER | da
30780 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f tatype] after co
30790 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 nversion is retu
307a0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c rned.)^.**.** Pl
307b0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 ease pay particu
307c0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f lar attention to
307d0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 the fact that t
307e0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 he pointer retur
307f0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
30800 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
30810 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
30820 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a ue_text()], or.*
30830 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 * [sqlite3_value
30840 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 _text16()] can b
30850 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 e invalidated by
30860 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 a subsequent ca
30870 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
30880 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 3_value_bytes()]
30890 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
308a0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 _bytes16()], [sq
308b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
308c0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
308d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
308e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ()]..**.** These
308f0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 routines must b
30900 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 e called from th
30910 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 e same thread as
30920 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 .** the SQL func
30930 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 tion that suppli
30940 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ed the [sqlite3_
30950 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 value*] paramete
30960 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 rs..*/.SQLITE_AP
30970 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
30980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 lite3_value_blob
30990 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
309a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
309b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
309c0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c ytes(sqlite3_val
309d0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
309e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c int sqlite3_val
309f0 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 ue_bytes16(sqlit
30a00 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
30a10 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 TE_API double sq
30a20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 lite3_value_doub
30a30 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
30a40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 *);.SQLITE_API i
30a50 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
30a60 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c _int(sqlite3_val
30a70 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
30a80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 sqlite3_int64 s
30a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 qlite3_value_int
30aa0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 64(sqlite3_value
30ab0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
30ac0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 onst unsigned ch
30ad0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 ar *sqlite3_valu
30ae0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 e_text(sqlite3_v
30af0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
30b00 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
30b10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
30b20 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t16(sqlite3_valu
30b30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
30b40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
30b50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
30b60 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 le(sqlite3_value
30b70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
30b80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
30b90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 e3_value_text16b
30ba0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a e(sqlite3_value*
30bb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
30bc0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f t sqlite3_value_
30bd0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c type(sqlite3_val
30be0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ue*);.SQLITE_API
30bf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c int sqlite3_val
30c00 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
30c10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
30c20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
30c30 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 : Obtain Aggrega
30c40 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 te Function Cont
30c50 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d ext.**.** Implem
30c60 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 entations of agg
30c70 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
30c80 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a ions use this.**
30c90 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f routine to allo
30ca0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 cate memory for
30cb0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 storing their st
30cc0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ate..**.** ^The
30cd0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 first time the s
30ce0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
30cf0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f _context(C,N) ro
30d00 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
30d10 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 .** for a partic
30d20 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 ular aggregate f
30d30 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a unction, SQLite.
30d40 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f ** allocates N o
30d50 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 f memory, zeroes
30d60 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 out that memory
30d70 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 , and returns a
30d80 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
30d90 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f e new memory. ^O
30da0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 n second and sub
30db0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
30dc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 .** sqlite3_aggr
30dd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
30de0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 for the same agg
30df0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
30e00 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 instance,.** the
30e10 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 same buffer is
30e20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 returned. Sqlit
30e30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
30e40 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c text() is normal
30e50 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 ly.** called onc
30e60 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 e for each invoc
30e70 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 ation of the xSt
30e80 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 ep callback and
30e90 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 then one.** last
30ea0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 time when the x
30eb0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 Final callback i
30ec0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 s invoked. ^(Wh
30ed0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 en no rows match
30ee0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 .** an aggregate
30ef0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 query, the xSte
30f00 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 p() callback of
30f10 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 the aggregate fu
30f20 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d nction.** implem
30f30 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 entation is neve
30f40 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 r called and xFi
30f50 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 nal() is called
30f60 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a exactly once..**
30f70 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c In those cases,
30f80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
30f90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 te_context() mig
30fa0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 ht be called for
30fb0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 the.** first ti
30fc0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 me from within x
30fd0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a Final().)^.**.**
30fe0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 ^The sqlite3_ag
30ff0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
31000 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 C,N) routine ret
31010 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
31020 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c ter if N is.** l
31030 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 ess than or equa
31040 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 l to zero or if
31050 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
31060 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a e error occurs..
31070 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 **.** ^(The amou
31080 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f nt of space allo
31090 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 cated by sqlite3
310a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
310b0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 xt(C,N) is.** de
310c0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
310d0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 N parameter on f
310e0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 irst successful
310f0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 call. Changing
31100 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 the.** value of
31110 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 N in subsequent
31120 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
31130 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
31140 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 t() within.** th
31150 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 e same aggregate
31160 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e function instan
31170 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 ce will not resi
31180 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a ze the memory.**
31190 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a allocation.)^.*
311a0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 *.** ^SQLite aut
311b0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 omatically frees
311c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
311d0 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c cated by .** sql
311e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
311f0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 ontext() when th
31200 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 e aggregate quer
31210 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a y concludes..**.
31220 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 ** The first par
31230 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 ameter must be a
31240 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
31250 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
31260 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 | SQL function
31270 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 context] that is
31280 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
31290 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 eter.** to the x
312a0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 Step or xFinal c
312b0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
312c0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
312d0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a the aggregate.**
312e0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
312f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 This routine mu
31300 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
31310 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
31320 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 d in which.** th
31330 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 e aggregate SQL
31340 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
31350 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ing..*/.SQLITE_A
31360 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 PI void *sqlite3
31370 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
31380 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 xt(sqlite3_conte
31390 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 xt*, int nBytes)
313a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
313b0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 F: User Data For
313c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a Functions.**.**
313d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 ^The sqlite3_us
313e0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 er_data() interf
313f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
31400 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
31410 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 nter that was th
31420 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 e pUserData para
31430 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 meter (the 5th p
31440 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 arameter).** of
31450 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 the [sqlite3_cre
31460 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a ate_function()].
31470 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
31480 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
31490 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 6()] routines th
314a0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a at originally.**
314b0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 registered the
314c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
314d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a ned function..**
314e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 .** This routine
314f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
31500 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
31510 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a read in which.**
31520 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
31530 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
31540 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f n is running..*/
31550 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
31560 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 *sqlite3_user_d
31570 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
31580 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
31590 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
315a0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 Connection For
315b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 Functions.**.**
315c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e ^The sqlite3_con
315d0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 text_db_handle()
315e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
315f0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
31600 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 the pointer to t
31610 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
31620 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 nection] (the 1s
31630 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 t parameter).**
31640 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
31650 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
31660 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 )].** and [sqlit
31670 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
31680 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 on16()] routines
31690 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 that originally
316a0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 .** registered t
316b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
316c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
316d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 .*/.SQLITE_API s
316e0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f qlite3 *sqlite3_
316f0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
31700 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
31710 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
31720 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 3REF: Function A
31730 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a uxiliary Data.**
31740 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e .** The followin
31750 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 g two functions
31760 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 may be used by s
31770 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
31780 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 ons to.** associ
31790 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 ate metadata wit
317a0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 h argument value
317b0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 s. If the same v
317c0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 alue is passed t
317d0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e o.** multiple in
317e0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 vocations of the
317f0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 same SQL functi
31800 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 on during query
31810 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 execution, under
31820 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 .** some circums
31830 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 tances the assoc
31840 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d iated metadata m
31850 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e ay be preserved.
31860 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 This may.** be
31870 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c used, for exampl
31880 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 e, to add a regu
31890 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d lar-expression m
318a0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a atching scalar.*
318b0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 * function. The
318c0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e compiled version
318d0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 of the regular
318e0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 expression is st
318f0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 ored as.** metad
31900 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 ata associated w
31910 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 ith the SQL valu
31920 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
31930 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 regular expressi
31940 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 on.** pattern.
31950 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 The compiled reg
31960 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
31970 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e can be reused on
31980 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 multiple.** inv
31990 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ocations of the
319a0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f same function so
319b0 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e that the origin
319c0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e al pattern strin
319d0 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 g.** does not ne
319e0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 ed to be recompi
319f0 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f led on each invo
31a00 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 cation..**.** ^T
31a10 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 he sqlite3_get_a
31a20 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
31a30 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
31a40 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 nter to the meta
31a50 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 data.** associat
31a60 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
31a70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
31a80 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 function with th
31a90 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a e Nth argument.*
31aa0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 * value to the a
31ab0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
31ac0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 ed function. ^If
31ad0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 no metadata has
31ae0 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 been ever.** be
31af0 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e en set for the N
31b00 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 th argument of t
31b10 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 he function, or
31b20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e if the correspon
31b30 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e ding.** function
31b40 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 parameter has c
31b50 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 hanged since the
31b60 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 meta-data was s
31b70 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 et,.** then sqli
31b80 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
31b90 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c ) returns a NULL
31ba0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 pointer..**.**
31bb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 ^The sqlite3_set
31bc0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 _auxdata() inter
31bd0 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d face saves the m
31be0 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 etadata.** point
31bf0 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 ed to by its 3rd
31c00 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 parameter as th
31c10 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 e metadata for t
31c20 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d he N-th.** argum
31c30 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 ent of the appli
31c40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
31c50 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 unction. Subseq
31c60 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
31c70 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
31c80 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 data() might ret
31c90 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 urn this data, i
31ca0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 f it has.** not
31cb0 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a been destroyed..
31cc0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 ** ^If it is not
31cd0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 NULL, SQLite wi
31ce0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 ll invoke the de
31cf0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 structor.** func
31d00 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 tion given by th
31d10 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
31d20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
31d30 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 uxdata() on.** t
31d40 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e he metadata when
31d50 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
31d60 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 ng function para
31d70 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a meter changes.**
31d80 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c or when the SQL
31d90 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c statement compl
31da0 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 etes, whichever
31db0 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a comes first..**.
31dc0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 ** SQLite is fre
31dd0 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 e to call the de
31de0 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f structor and dro
31df0 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e p metadata on an
31e00 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f y.** parameter o
31e10 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 f any function a
31e20 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 t any time. ^Th
31e30 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 e only guarantee
31e40 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 is that.** the
31e50 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 destructor will
31e60 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 be called before
31e70 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 the metadata is
31e80 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 dropped..**.**
31e90 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d ^(In practice, m
31ea0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 etadata is prese
31eb0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e rved between fun
31ec0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a ction calls for.
31ed0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 ** expressions t
31ee0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 hat are constant
31ef0 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
31f00 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 . This includes
31f10 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 literal.** value
31f20 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 s and [parameter
31f30 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 s].)^.**.** Thes
31f40 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 e routines must
31f50 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
31f60 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
31f70 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 n which.** the S
31f80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
31f90 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 unning..*/.SQLIT
31fa0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
31fb0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
31fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
31fd0 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 , int N);.SQLITE
31fe0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
31ff0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 3_set_auxdata(sq
32000 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
32010 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f int N, void*, vo
32020 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a id (*)(void*));.
32030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32040 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 : Constants Defi
32050 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 ning Special Des
32060 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 tructor Behavior
32070 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
32080 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 special values
32090 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 for the destruct
320a0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 or that is passe
320b0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 d in as the.** f
320c0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f inal argument to
320d0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
320e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
320f0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 lob()]. ^If the
32100 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 destructor.** a
32110 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 rgument is SQLIT
32120 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 E_STATIC, it mea
32130 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 ns that the cont
32140 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 ent pointer is c
32150 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 onstant.** and w
32160 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 ill never change
32170 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e . It does not n
32180 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f eed to be destro
32190 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 yed. ^The.** SQ
321a0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 LITE_TRANSIENT v
321b0 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 alue means that
321c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c the content will
321d0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 likely change i
321e0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 n.** the near fu
321f0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 ture and that SQ
32200 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 Lite should make
32210 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
32220 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 copy of.** the
32230 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 content before r
32240 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 eturning..**.**
32250 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e The typedef is n
32260 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b ecessary to work
32270 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 around problems
32280 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 in certain.** C
32290 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 ++ compilers. S
322a0 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e ee ticket #2191.
322b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 .*/.typedef void
322c0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 (*sqlite3_destr
322d0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 uctor_type)(void
322e0 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 *);.#define SQLI
322f0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 TE_STATIC (
32300 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 (sqlite3_destruc
32310 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 tor_type)0).#def
32320 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
32330 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 IENT ((sqlite3
32340 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 _destructor_type
32350 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 )-1)../*.** CAPI
32360 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 3REF: Setting Th
32370 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 e Result Of An S
32380 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a QL Function.**.*
32390 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
323a0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 are used by the
323b0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c xFunc or xFinal
323c0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a callbacks that.
323d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c ** implement SQL
323e0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 functions and a
323f0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a ggregates. See.
32400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
32410 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
32420 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
32430 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
32440 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e .** for addition
32450 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
32460 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
32470 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 tions work very
32480 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 much like the [p
32490 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 arameter binding
324a0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 ] family of.** f
324b0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f unctions used to
324c0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 bind values to
324d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 host parameters
324e0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 in prepared stat
324f0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 ements..** Refer
32500 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 to the [SQL par
32510 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 ameter] document
32520 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 ation for additi
32530 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
32540 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
32550 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
32560 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
32570 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f s the result fro
32580 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 m.** an applicat
32590 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
325a0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 tion to be the B
325b0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e LOB whose conten
325c0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 t is pointed.**
325d0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 to by the second
325e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 parameter and w
325f0 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 hich is N bytes
32600 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 long where N is
32610 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 the.** third par
32620 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ameter..**.** ^T
32630 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
32640 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 t_zeroblob() int
32650 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 erfaces set the
32660 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 result of.** the
32670 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
32680 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
32690 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 be a BLOB conta
326a0 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a ining all zero.*
326b0 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 * bytes and N by
326c0 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 tes in size, whe
326d0 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 re N is the valu
326e0 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 e of the 2nd par
326f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ameter..**.** ^T
32700 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
32710 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 t_double() inter
32720 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
32730 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 sult from.** an
32740 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
32750 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
32760 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f be a floating po
32770 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 int value specif
32780 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e ied.** by its 2n
32790 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
327a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
327b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e esult_error() an
327c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
327d0 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 _error16() funct
327e0 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 ions.** cause th
327f0 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 e implemented SQ
32800 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 L function to th
32810 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e row an exception
32820 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 ..** ^SQLite use
32830 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 s the string poi
32840 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a nted to by the.*
32850 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * 2nd parameter
32860 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c of sqlite3_resul
32870 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c t_error() or sql
32880 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
32890 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 r16().** as the
328a0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 text of an error
328b0 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 message. ^SQLi
328c0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 te interprets th
328d0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 e error.** messa
328e0 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 ge string from s
328f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
32900 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 ror() as UTF-8.
32910 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 ^SQLite.** inter
32920 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 prets the string
32930 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
32940 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 sult_error16() a
32950 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 s UTF-16 in nati
32960 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 ve.** byte order
32970 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 . ^If the third
32980 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
32990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
329a0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
329b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
329c0 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 6() is negative
329d0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
329e0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a s as the error.*
329f0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 * message all te
32a00 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 xt up through th
32a10 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 e first zero cha
32a20 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 racter..** ^If t
32a30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
32a40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
32a50 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a sult_error() or.
32a60 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
32a70 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e t_error16() is n
32a80 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e on-negative then
32a90 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 SQLite takes th
32aa0 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 at many.** bytes
32ab0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 (not characters
32ac0 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 ) from the 2nd p
32ad0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 arameter as the
32ae0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a error message..*
32af0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
32b00 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e esult_error() an
32b10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
32b20 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f _error16().** ro
32b30 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 utines make a pr
32b40 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
32b50 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
32b60 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 text before.** t
32b70 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e hey return. Hen
32b80 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 ce, the calling
32b90 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 function can dea
32ba0 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f llocate or.** mo
32bb0 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 dify the text af
32bc0 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 ter they return
32bd0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a without harm..**
32be0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
32bf0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 sult_error_code(
32c00 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 ) function chang
32c10 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 es the error cod
32c20 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
32c30 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 SQLite as a res
32c40 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 ult of an error
32c50 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 in a function.
32c60 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 ^By default,.**
32c70 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 the error code i
32c80 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 s SQLITE_ERROR.
32c90 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 ^A subsequent c
32ca0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 all to sqlite3_r
32cb0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a esult_error().**
32cc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
32cd0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 lt_error16() res
32ce0 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f ets the error co
32cf0 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 de to SQLITE_ERR
32d00 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 OR..**.** ^The s
32d10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
32d20 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 ror_toobig() int
32d30 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 erface causes SQ
32d40 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e Lite to throw an
32d50 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 .** error indica
32d60 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 ting that a stri
32d70 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f ng or BLOB is to
32d80 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 o long to repres
32d90 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ent..**.** ^The
32da0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
32db0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 rror_nomem() int
32dc0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 erface causes SQ
32dd0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e Lite to throw an
32de0 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 .** error indica
32df0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f ting that a memo
32e00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 ry allocation fa
32e10 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 iled..**.** ^The
32e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
32e30 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 int() interface
32e40 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 sets the return
32e50 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 value.** of the
32e60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
32e70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
32e80 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 be the 32-bit si
32e90 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 gned integer.**
32ea0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 value given in t
32eb0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e he 2nd argument.
32ec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
32ed0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 _result_int64()
32ee0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
32ef0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a he return value.
32f00 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 ** of the applic
32f10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
32f20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 nction to be the
32f30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
32f40 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 nteger.** value
32f50 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 given in the 2nd
32f60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
32f70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
32f80 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 sult_null() inte
32f90 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
32fa0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f eturn value.** o
32fb0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f f the applicatio
32fc0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
32fd0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a on to be NULL..*
32fe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
32ff0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 3_result_text(),
33000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33010 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c text16(),.** sql
33020 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
33030 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 16le(), and sqli
33040 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 te3_result_text1
33050 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 6be() interfaces
33060 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 .** set the retu
33070 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 rn value of the
33080 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
33090 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
330a0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 be.** a text str
330b0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 ing which is rep
330c0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d resented as UTF-
330d0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 8, UTF-16 native
330e0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 byte order,.**
330f0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e UTF-16 little en
33100 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 dian, or UTF-16
33110 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 big endian, resp
33120 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 ectively..** ^SQ
33130 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 Lite takes the t
33140 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 ext result from
33150 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
33160 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 from.** the 2nd
33170 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 parameter of the
33180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33190 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
331a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 ..** ^If the 3rd
331b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
331c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
331d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
331e0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 s.** is negative
331f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 , then SQLite ta
33200 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 kes result text
33210 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 from the 2nd par
33220 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 ameter.** throug
33230 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f h the first zero
33240 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e character..** ^
33250 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d If the 3rd param
33260 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
33270 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
33280 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 interfaces.** i
33290 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 s non-negative,
332a0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 then as many byt
332b0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 es (not characte
332c0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a rs) of the text.
332d0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
332e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
332f0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 er are taken as
33300 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
33310 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 defined.** funct
33320 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 ion result. If
33330 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
33340 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 r is non-negativ
33350 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 e, then it.** mu
33360 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
33370 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 ffset into the s
33380 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 tring where the
33390 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
333a0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 ould.** appear i
333b0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 f the string whe
333c0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 re NUL terminate
333d0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 d. If any NUL c
333e0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a haracters occur.
333f0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 ** in the string
33400 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 at a byte offse
33410 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 t that is less t
33420 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 han the value of
33430 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 the 3rd.** para
33440 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
33450 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
33460 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d will contain em
33470 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 bedded NULs and
33480 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 the.** result of
33490 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 expressions ope
334a0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 rating on string
334b0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 s with embedded
334c0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 NULs is undefine
334d0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 d..** ^If the 4t
334e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
334f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
33500 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
33510 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 es.** or sqlite3
33520 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 _result_blob is
33530 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
33540 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 er, then SQLite
33550 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 calls that.** fu
33560 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 nction as the de
33570 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 structor on the
33580 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 text or BLOB res
33590 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a ult when it has.
335a0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e ** finished usin
335b0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a g that result..*
335c0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 * ^If the 4th pa
335d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
335e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
335f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f xt* interfaces o
33600 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
33610 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
33620 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
33630 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 ant SQLITE_STATI
33640 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a C, then SQLite.*
33650 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 * assumes that t
33660 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 he text or BLOB
33670 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e result is in con
33680 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 stant space and
33690 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 does not.** copy
336a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
336b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f the parameter no
336c0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 r call a destruc
336d0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 tor on the conte
336e0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 nt.** when it ha
336f0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
33700 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a that result..**
33710 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 ^If the 4th par
33720 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 ameter to the sq
33730 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
33740 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a t* interfaces.**
33750 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
33760 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 lt_blob is the s
33770 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 pecial constant
33780 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 SQLITE_TRANSIENT
33790 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 .** then SQLite
337a0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 makes a copy of
337b0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 the result into
337c0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 space obtained f
337d0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c rom.** from [sql
337e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 ite3_malloc()] b
337f0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 efore it returns
33800 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
33810 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
33820 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 e() interface se
33830 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 ts the result of
33840 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
33850 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
33860 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 tion to be a cop
33870 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 y the.** [unprot
33880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
33890 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 lue] object spec
338a0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 ified by the 2nd
338b0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 parameter. ^Th
338c0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 e.** sqlite3_res
338d0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 ult_value() inte
338e0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f rface makes a co
338f0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 py of the [sqlit
33900 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 e3_value].** so
33910 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 that the [sqlite
33920 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 3_value] specifi
33930 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 ed in the parame
33940 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f ter may change o
33950 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 r.** be dealloca
33960 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 ted after sqlite
33970 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
33980 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 returns without
33990 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 harm..** ^A [pr
339a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
339b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 value] object ma
339c0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 y always be used
339d0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e where an.** [un
339e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
339f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
33a00 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 is required, so
33a10 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f either.** kind o
33a20 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 f [sqlite3_value
33a30 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 ] object can be
33a40 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 used with this i
33a50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
33a60 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 If these routine
33a70 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f s are called fro
33a80 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 m within the dif
33a90 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a ferent thread.**
33aa0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f than the one co
33ab0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 ntaining the app
33ac0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
33ad0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 function that r
33ae0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b eceived.** the [
33af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d sqlite3_context]
33b00 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 pointer, the re
33b10 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
33b20 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ned..*/.SQLITE_A
33b30 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
33b40 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 result_blob(sqli
33b50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
33b60 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
33b70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
33b80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
33b90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
33ba0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 double(sqlite3_c
33bb0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 ontext*, double)
33bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
33bd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
33be0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 _error(sqlite3_c
33bf0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
33c00 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 har*, int);.SQLI
33c10 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
33c20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
33c30 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
33c40 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
33c50 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
33c60 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
33c70 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f result_error_too
33c80 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 big(sqlite3_cont
33c90 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
33ca0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
33cb0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
33cc0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 m(sqlite3_contex
33cd0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
33ce0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
33cf0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 ult_error_code(s
33d00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
33d10 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 int);.SQLITE_AP
33d20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 I void sqlite3_r
33d30 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 esult_int(sqlite
33d40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
33d50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
33d60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
33d70 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 _int64(sqlite3_c
33d80 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 ontext*, sqlite3
33d90 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f _int64);.SQLITE_
33da0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
33db0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c _result_null(sql
33dc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
33dd0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
33de0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
33df0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext(sqlite3_cont
33e00 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 ext*, const char
33e10 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
33e20 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
33e30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
33e40 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 _result_text16(s
33e50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
33e60 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
33e70 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
33e80 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
33e90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
33ea0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 lt_text16le(sqli
33eb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
33ec0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
33ed0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
33ee0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
33ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
33f00 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
33f10 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
33f20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
33f30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
33f40 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
33f50 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
33f60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
33f70 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 *, sqlite3_value
33f80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
33f90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
33fa0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 lt_zeroblob(sqli
33fb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e te3_context*, in
33fc0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 t n);../*.** CAP
33fd0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 I3REF: Define Ne
33fe0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 w Collating Sequ
33ff0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ences.**.** ^The
34000 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 se functions add
34010 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 , remove, or mod
34020 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e ify a [collation
34030 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 ] associated.**
34040 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
34050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
34060 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 pecified as the
34070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
34080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 **.** ^The name
34090 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e of the collation
340a0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
340b0 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 ng.** for sqlite
340c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
340d0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 on() and sqlite3
340e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
340f0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 n_v2().** and a
34100 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e UTF-16 string in
34110 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
34120 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 er for sqlite3_c
34130 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 reate_collation1
34140 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6()..** ^Collati
34150 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f on names that co
34160 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f mpare equal acco
34170 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 rding to [sqlite
34180 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 3_strnicmp()] ar
34190 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 e.** considered
341a0 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e to be the same n
341b0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ame..**.** ^(The
341c0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
341d0 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 (eTextRep) must
341e0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f be one of the co
341f0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e nstants:.** <ul>
34200 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
34210 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 _UTF8],.** <li>
34220 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
34230 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ,.** <li> [SQLIT
34240 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c E_UTF16BE],.** <
34250 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 li> [SQLITE_UTF1
34260 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 6], or.** <li> [
34270 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 SQLITE_UTF16_ALI
34280 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 GNED]..** </ul>)
34290 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 ^.** ^The eTextR
342a0 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 ep argument dete
342b0 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 rmines the encod
342c0 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 ing of strings p
342d0 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 assed.** to the
342e0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
342f0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 on callback, xCa
34300 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 llback..** ^The
34310 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 [SQLITE_UTF16] a
34320 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 nd [SQLITE_UTF16
34330 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 _ALIGNED] values
34340 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a for eTextRep.**
34350 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 force strings t
34360 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 o be UTF16 with
34370 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
34380 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 r..** ^The [SQLI
34390 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
343a0 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 ] value for eTex
343b0 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 tRep forces stri
343c0 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 ngs to begin.**
343d0 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 on an even byte
343e0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e address..**.** ^
343f0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d The fourth argum
34400 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e ent, pArg, is an
34410 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
34420 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 a pointer that i
34430 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f s passed.** thro
34440 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 ugh as the first
34450 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
34460 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
34470 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ion callback..**
34480 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 .** ^The fifth a
34490 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 rgument, xCallba
344a0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ck, is a pointer
344b0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e to the collatin
344c0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e g function..** ^
344d0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 Multiple collati
344e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e ng functions can
344f0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 be registered u
34500 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 sing the same na
34510 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 me but.** with d
34520 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 ifferent eTextRe
34530 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 p parameters and
34540 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
34550 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 whichever.** fu
34560 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
34570 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 the least amount
34580 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f of data transfo
34590 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 rmation..** ^If
345a0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 the xCallback ar
345b0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 gument is NULL t
345c0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e hen the collatin
345d0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a g function is.**
345e0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e deleted. ^When
345f0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 all collating f
34600 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 unctions having
34610 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 the same name ar
34620 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 e deleted,.** th
34630 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 at collation is
34640 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 no longer usable
34650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c ..**.** ^The col
34660 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
34670 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
34680 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 ked with a copy
34690 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 of the pArg .**
346a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
346b0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 pointer and wit
346c0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e h two strings in
346d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 the encoding sp
346e0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
346f0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d e eTextRep argum
34700 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 ent. The collat
34710 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 ing function mus
34720 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 t return an.** i
34730 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e nteger that is n
34740 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f egative, zero, o
34750 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 r positive.** if
34760 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e the first strin
34770 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 g is less than,
34780 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 equal to, or gre
34790 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 ater than the se
347a0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 cond,.** respect
347b0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 ively. A collat
347c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 ing function mus
347d0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 t always return
347e0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a the same answer.
347f0 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d ** given the sam
34800 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 e inputs. If tw
34810 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 o or more collat
34820 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ing functions ar
34830 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 e registered.**
34840 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c to the same coll
34850 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e ation name (usin
34860 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 g different eTex
34870 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 tRep values) the
34880 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 n all.** must gi
34890 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 ve an equivalent
348a0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 answer when inv
348b0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 oked with equiva
348c0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a lent strings..**
348d0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 The collating f
348e0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 unction must obe
348f0 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 y the following
34900 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 properties for a
34910 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c ll.** strings A,
34920 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a B, and C:.**.**
34930 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 <ol>.** <li> If
34940 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e A==B then B==A.
34950 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 .** <li> If A==B
34960 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 and B==C then A
34970 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 ==C..** <li> If
34980 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 A<B THEN B>
34990 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 ;A..** <li> If A
349a0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 <B and B<C
349b0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a then A<C..**
349c0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </ol>.**.** If
349d0 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 a collating func
349e0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f tion fails any o
349f0 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 f the above cons
34a00 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 traints and that
34a10 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 .** collating fu
34a20 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 nction is regis
34a30 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 tered and used,
34a40 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
34a50 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 r of SQLite.** i
34a60 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
34a70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
34a80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
34a90 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 _v2() works like
34aa0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
34ab0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 collation().** w
34ac0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e ith the addition
34ad0 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 that the xDestr
34ae0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 oy callback is i
34af0 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 nvoked on pArg w
34b00 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 hen.** the colla
34b10 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 ting function is
34b20 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f deleted..** ^Co
34b30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
34b40 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 s are deleted wh
34b50 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 en they are over
34b60 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a ridden by later.
34b70 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 ** calls to the
34b80 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 collation creati
34b90 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 on functions or
34ba0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 when the.** [dat
34bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
34bc0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e ] is closed usin
34bd0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 g [sqlite3_close
34be0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ()]..**.** ^The
34bf0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 xDestroy callbac
34c00 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 k is <u>not</u>
34c10 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a called if the .*
34c20 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 * sqlite3_create
34c30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 _collation_v2()
34c40 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 function fails.
34c50 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 Applications th
34c60 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c at invoke.** sql
34c70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c ite3_create_coll
34c80 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 ation_v2() with
34c90 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 a non-NULL xDest
34ca0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f roy argument sho
34cb0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 uld .** check th
34cc0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e e return code an
34cd0 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 d dispose of the
34ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
34cf0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 a pointer.** the
34d00 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 mselves rather t
34d10 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 han expecting SQ
34d20 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 Lite to deal wit
34d30 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a h it for them..*
34d40 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 * This is differ
34d50 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f ent from every o
34d60 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
34d70 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f rface. The inco
34d80 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 nsistency .** is
34d90 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 unfortunate but
34da0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 cannot be chang
34db0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ed without break
34dc0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a ing backwards .*
34dd0 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e * compatibility.
34de0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
34df0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 [sqlite3_colla
34e00 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 tion_needed()] a
34e10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c nd [sqlite3_coll
34e20 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 ation_needed16()
34e30 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
34e40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 int sqlite3_cre
34e50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 ate_collation(.
34e60 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f sqlite3*, . co
34e70 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
34e80 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 . int eTextRep
34e90 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c , . void *pArg,
34ea0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 . int(*xCompare
34eb0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
34ec0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 t void*,int,cons
34ed0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 t void*).);.SQLI
34ee0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
34ef0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
34f00 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 ion_v2(. sqlite
34f10 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 3*, . const cha
34f20 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 r *zName, . int
34f30 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f eTextRep, . vo
34f40 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 id *pArg,. int(
34f50 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a *xCompare)(void*
34f60 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
34f70 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a ,int,const void*
34f80 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
34f90 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 roy)(void*).);.S
34fa0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
34fb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
34fc0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 lation16(. sqli
34fd0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 te3*, . const v
34fe0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e oid *zName,. in
34ff0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 t eTextRep, . v
35000 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 oid *pArg,. int
35010 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 (*xCompare)(void
35020 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
35030 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 *,int,const void
35040 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *).);../*.** CAP
35050 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e I3REF: Collation
35060 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b Needed Callback
35070 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 s.**.** ^To avoi
35080 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 d having to regi
35090 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 ster all collati
350a0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 on sequences bef
350b0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a ore a database.*
350c0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 * can be used, a
350d0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b single callback
350e0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
350f0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68 registered with
35100 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
35110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f e connection] to
35120 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e be invoked when
35130 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 ever an undefine
35140 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 d collation.** s
35150 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 equence is requi
35160 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 red..**.** ^If t
35170 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
35180 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 egistered using
35190 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c the sqlite3_coll
351a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 ation_needed() A
351b0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 PI,.** then it i
351c0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d s passed the nam
351d0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 es of undefined
351e0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e collation sequen
351f0 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a ces as strings.*
35200 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 * encoded in UTF
35210 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f -8. ^If sqlite3_
35220 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 collation_needed
35230 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 16() is used,.**
35240 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 the names are p
35250 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 assed as UTF-16
35260 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 in machine nativ
35270 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a e byte order..**
35280 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 ^A call to eith
35290 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c er function repl
352a0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e aces the existin
352b0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 g collation-need
352c0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a ed callback..**.
352d0 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 ** ^(When the ca
352e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
352f0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67 d, the first arg
35300 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 ument passed is
35310 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 a copy.** of the
35320 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
35330 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c to sqlite3_coll
35340 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f ation_needed() o
35350 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c r.** sqlite3_col
35360 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 lation_needed16(
35370 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 ). The second a
35380 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 rgument is the d
35390 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
353a0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 ction. The thir
353b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e d argument is on
353c0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 e of [SQLITE_UTF
353d0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 8], [SQLITE_UTF1
353e0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 6BE],.** or [SQL
353f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e ITE_UTF16LE], in
35400 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 dicating the mos
35410 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d t desirable form
35420 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f of the collatio
35430 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 n.** sequence fu
35440 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e nction required.
35450 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 The fourth par
35460 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 ameter is the na
35470 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 me of the.** req
35480 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 uired collation
35490 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a sequence.)^.**.*
354a0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 * The callback f
354b0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 unction should r
354c0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69 egister the desi
354d0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 red collation us
354e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
354f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
35500 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
35510 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
35520 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
35530 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
35540 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 tion_v2()]..*/.S
35550 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
35560 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f lite3_collation_
35570 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 needed(. sqlite
35580 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 3*, . void*, .
35590 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 void(*)(void*,s
355a0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 qlite3*,int eTex
355b0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a tRep,const char*
355c0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
355d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c int sqlite3_coll
355e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a ation_needed16(.
355f0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 sqlite3*, . v
35600 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 oid*,. void(*)(
35610 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 void*,sqlite3*,i
35620 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 nt eTextRep,cons
35630 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 t void*).);..#if
35640 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 def SQLITE_HAS_C
35650 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 ODEC./*.** Speci
35660 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 fy the key for a
35670 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 n encrypted data
35680 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 base. This rout
35690 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a ine should be.**
356a0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 called right af
356b0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ter sqlite3_open
356c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ()..**.** The co
356d0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 de to implement
356e0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 this API is not
356f0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 available in the
35700 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a public release.
35710 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f ** of SQLite..*/
35720 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
35730 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 sqlite3_key(. s
35740 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
35750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
35760 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 Database to be
35770 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e rekeyed */. con
35780 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
35790 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
357a0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a he key */.);../*
357b0 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b .** Change the k
357c0 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 ey on an open da
357d0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 tabase. If the
357e0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 current database
357f0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 is not.** encry
35800 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 pted, this routi
35810 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 ne will encrypt
35820 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 it. If pNew==0
35830 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a or nNew==0, the.
35840 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 ** database is d
35850 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 ecrypted..**.**
35860 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c The code to impl
35870 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 ement this API i
35880 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 s not available
35890 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 in the public re
358a0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 lease.** of SQLi
358b0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 te..*/.SQLITE_AP
358c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 I int sqlite3_re
358d0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a key(. sqlite3 *
358e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 db,
358f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
35900 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 e to be rekeyed
35910 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
35920 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 *pKey, int nKey
35930 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b /* The new k
35940 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ey */.);../*.**
35950 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 Specify the acti
35960 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 vation key for a
35970 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 SEE database.
35980 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 Unless .** activ
35990 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 ated, none of th
359a0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 e SEE routines w
359b0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c ill work..*/.SQL
359c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
359d0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 ite3_activate_se
359e0 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 e(. const char
359f0 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 *zPassPhrase
35a00 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f /* Activatio
35a10 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 n phrase */.);.#
35a20 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 endif..#ifdef SQ
35a30 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f LITE_ENABLE_CERO
35a40 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 D./*.** Specify
35a50 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b the activation k
35a60 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 ey for a CEROD d
35a70 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 atabase. Unless
35a80 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 .** activated,
35a90 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f none of the CERO
35aa0 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 D routines will
35ab0 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f work..*/.SQLITE_
35ac0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
35ad0 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 _activate_cerod(
35ae0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
35af0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 PassPhrase
35b00 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 /* Activation
35b10 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e phrase */.);.#en
35b20 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 dif../*.** CAPI3
35b30 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 REF: Suspend Exe
35b40 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f cution For A Sho
35b50 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 rt Time.**.** Th
35b60 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 e sqlite3_sleep(
35b70 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 ) function cause
35b80 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 s the current th
35b90 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 read to suspend
35ba0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 execution.** for
35bb0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 at least a numb
35bc0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e er of millisecon
35bd0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 ds specified in
35be0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a its parameter..*
35bf0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 *.** If the oper
35c00 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 ating system doe
35c10 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c s not support sl
35c20 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74 eep requests wit
35c30 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 h.** millisecond
35c40 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e time resolution
35c50 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 , then the time
35c60 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 will be rounded
35c70 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 up to.** the nea
35c80 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 rest second. The
35c90 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 number of milli
35ca0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
35cb0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 actually.** req
35cc0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 uested from the
35cd0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
35ce0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
35cf0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c .** ^SQLite impl
35d00 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 ements this inte
35d10 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 rface by calling
35d20 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a the xSleep().**
35d30 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 method of the d
35d40 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
35d50 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 vfs] object. If
35d60 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 the xSleep() me
35d70 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 thod.** of the d
35d80 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f efault VFS is no
35d90 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f t implemented co
35da0 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 rrectly, or not
35db0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a implemented at.*
35dc0 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 * all, then the
35dd0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 behavior of sqli
35de0 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 te3_sleep() may
35df0 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 deviate from the
35e00 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 description.**
35e10 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 in the previous
35e20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 paragraphs..*/.S
35e30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
35e40 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 lite3_sleep(int)
35e50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
35e60 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 F: Name Of The F
35e70 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 older Holding Te
35e80 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a mporary Files.**
35e90 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c .** ^(If this gl
35ea0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 obal variable is
35eb0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
35ec0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
35ed0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 is.** the name
35ee0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b of a folder (a.k
35ef0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 .a. directory),
35f00 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 then all tempora
35f10 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 ry files.** crea
35f20 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 ted by SQLite wh
35f30 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 en using a built
35f40 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 -in [sqlite3_vfs
35f50 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 | VFS].** will
35f60 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 be placed in tha
35f70 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 t directory.)^
35f80 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c ^If this variabl
35f90 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 e.** is a NULL p
35fa0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
35fb0 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 ite performs a s
35fc0 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 earch for an app
35fd0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 ropriate.** temp
35fe0 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 orary file direc
35ff0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 tory..**.** It i
36000 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 s not safe to re
36010 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ad or modify thi
36020 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f s variable in mo
36030 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 re than one.** t
36040 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e hread at a time.
36050 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 It is not safe
36060 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 to read or modi
36070 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 fy this variable
36080 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 .** if a [databa
36090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
360a0 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 s being used at
360b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e the same time in
360c0 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 a separate.** t
360d0 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 hread..** It is
360e0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 intended that th
360f0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 is variable be s
36100 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 et once.** as pa
36110 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e rt of process in
36120 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 itialization and
36130 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 before any SQLi
36140 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 te interface.**
36150 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 routines have be
36160 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 en called and th
36170 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
36180 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 remain unchange
36190 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e d.** thereafter.
361a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d .**.** ^The [tem
361b0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
361c0 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f y pragma] may mo
361d0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 dify this variab
361e0 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 le and cause.**
361f0 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d it to point to m
36200 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
36210 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
36220 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d loc]. ^Furtherm
36230 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d ore,.** the [tem
36240 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
36250 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 y pragma] always
36260 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e assumes that an
36270 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 y string.** that
36280 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 this variable p
36290 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 oints to is held
362a0 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 in memory obtai
362b0 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 ned from .** [sq
362c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e lite3_malloc] an
362d0 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 d the pragma may
362e0 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 attempt to free
362f0 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 that memory.**
36300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
36310 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 ree]..** Hence,
36320 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 if this variable
36330 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 is modified dir
36340 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 ectly, either it
36350 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 should be.** ma
36360 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 de NULL or made
36370 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f to point to memo
36380 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
36390 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
363a0 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 ].** or else the
363b0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d use of the [tem
363c0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
363d0 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 y pragma] should
363e0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a be avoided..**.
363f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
36400 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 ndows Runtime us
36410 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 ers:</b> The te
36420 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 mporary director
36430 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a y must be set.**
36440 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e prior to callin
36450 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d g [sqlite3_open]
36460 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 or [sqlite3_ope
36470 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 n_v2]. Otherwis
36480 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 e, various.** fe
36490 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 atures that requ
364a0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 ire the use of t
364b0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d emporary files m
364c0 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 ay fail. Here i
364d0 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 s an.** example
364e0 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 of how to do thi
364f0 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 s using C++ with
36500 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e the Windows Run
36510 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f time:.**.** <blo
36520 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
36530 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d LPCWSTR zPath =
36540 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 Windows::Storag
36550 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 e::ApplicationDa
36560 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a ta::Current->.**
36570 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 Temp
36580 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 oraryFolder->Pat
36590 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 h->Data();.** ch
365a0 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b ar zPathBuf[
365b0 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 MAX_PATH + 1]
365c0 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 ;;.** memset(zPa
365d0 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 thBuf, 0, sizeof
365e0 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 (zPathBuf));.**
365f0 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 WideCharToMultiB
36600 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 yte(CP_UTF8, 0,
36610 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 zPath, -1, zPath
36620 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 Buf, sizeof(zPat
36630 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b hBuf),.**
36640 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 NULL, NULL)
36650 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d ;.** sqlite3_tem
36660 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 p_directory = sq
36670 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 lite3_mprintf("%
36680 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a s", zPathBuf);.*
36690 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
366a0 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f uote>.*/.SQLITE_
366b0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 API SQLITE_EXTER
366c0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f N char *sqlite3_
366d0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a temp_directory;.
366e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
366f0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c Name Of The Fol
36700 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 der Holding Data
36710 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a base Files.**.**
36720 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 ^(If this globa
36730 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 l variable is ma
36740 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 de to point to a
36750 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 string which is
36760 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 .** the name of
36770 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e a folder (a.k.a.
36780 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 directory), the
36790 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 n all database f
367a0 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 iles.** specifie
367b0 64 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 d with a relativ
367c0 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 e pathname and c
367d0 72 65 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 reated or access
367e0 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 ed by.** SQLite
367f0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 when using a bui
36800 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 lt-in windows [s
36810 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 qlite3_vfs | VFS
36820 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 ] will be assume
36830 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 d.** to be relat
36840 69 76 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 ive to that dire
36850 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 ctory.)^ ^If thi
36860 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 s variable is a
36870 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c NULL.** pointer,
36880 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 then SQLite ass
36890 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 umes that all da
368a0 74 61 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 tabase files spe
368b0 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 cified.** with a
368c0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 relative pathna
368d0 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 me are relative
368e0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 to the current d
368f0 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 irectory.** for
36900 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e the process. On
36910 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 ly the windows V
36920 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 FS makes use of
36930 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 this global.** v
36940 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 ariable; it is i
36950 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e gnored by the un
36960 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 ix VFS..**.** Ch
36970 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 anging the value
36980 20 6f 66 20 74 68 69 73 20 76 61 72 69 61 62 6c of this variabl
36990 65 20 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 e while a databa
369a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
369b0 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 .** open can res
369c0 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 ult in a corrupt
369d0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a database..**.**
369e0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 It is not safe
369f0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 to read or modif
36a00 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 y this variable
36a10 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 in more than one
36a20 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 .** thread at a
36a30 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 time. It is not
36a40 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 safe to read or
36a50 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 modify this var
36a60 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 iable.** if a [d
36a70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
36a80 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 on] is being use
36a90 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 d at the same ti
36aa0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 me in a separate
36ab0 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 .** thread..** I
36ac0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 t is intended th
36ad0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 at this variable
36ae0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 be set once.**
36af0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 as part of proce
36b00 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
36b10 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 n and before any
36b20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
36b30 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 e.** routines ha
36b40 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 ve been called a
36b50 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 nd that this var
36b60 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 iable remain unc
36b70 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 hanged.** therea
36b80 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 fter..**.** ^The
36b90 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 [data_store_dir
36ba0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d ectory pragma] m
36bb0 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 ay modify this v
36bc0 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 ariable and caus
36bd0 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 e.** it to point
36be0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 to memory obtai
36bf0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
36c00 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 3_malloc]. ^Fur
36c10 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 thermore,.** the
36c20 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 [data_store_dir
36c30 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 ectory pragma] a
36c40 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 lways assumes th
36c50 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a at any string.**
36c60 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 that this varia
36c70 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 ble points to is
36c80 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 held in memory
36c90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a obtained from .*
36ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
36cb0 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d c] and the pragm
36cc0 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f a may attempt to
36cd0 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 free that memor
36ce0 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 y.** using [sqli
36cf0 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 te3_free]..** He
36d00 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 nce, if this var
36d10 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 iable is modifie
36d20 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 d directly, eith
36d30 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a er it should be.
36d40 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 ** made NULL or
36d50 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f made to point to
36d60 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
36d70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
36d80 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 alloc].** or els
36d90 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 e the use of the
36da0 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 [data_store_dir
36db0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 ectory pragma] s
36dc0 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 hould be avoided
36dd0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
36de0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 SQLITE_EXTERN ch
36df0 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 ar *sqlite3_data
36e00 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a _directory;../*.
36e10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
36e20 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 t For Auto-Commi
36e30 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 t Mode.** KEYWOR
36e40 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 DS: {autocommit
36e50 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 mode}.**.** ^The
36e60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 sqlite3_get_aut
36e70 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 ocommit() interf
36e80 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ace returns non-
36e90 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 zero or.** zero
36ea0 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 if the given dat
36eb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
36ec0 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e is or is not in
36ed0 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 autocommit mode
36ee0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c ,.** respectivel
36ef0 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 y. ^Autocommit
36f00 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 mode is on by de
36f10 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 fault..** ^Autoc
36f20 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 ommit mode is di
36f30 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 sabled by a [BEG
36f40 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a IN] statement..*
36f50 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f * ^Autocommit mo
36f60 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 de is re-enabled
36f70 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f by a [COMMIT] o
36f80 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a r [ROLLBACK]..**
36f90 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b .** If certain k
36fa0 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f inds of errors o
36fb0 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d ccur on a statem
36fc0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c ent within a mul
36fd0 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ti-statement.**
36fe0 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 transaction (err
36ff0 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 ors including [S
37000 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 QLITE_FULL], [SQ
37010 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 LITE_IOERR],.**
37020 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 [SQLITE_NOMEM],
37030 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 [SQLITE_BUSY], a
37040 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 nd [SQLITE_INTER
37050 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a RUPT]) then the.
37060 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d ** transaction m
37070 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 ight be rolled b
37080 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ack automaticall
37090 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 y. The only way
370a0 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 to.** find out
370b0 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 whether SQLite a
370c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c utomatically rol
370d0 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 led back the tra
370e0 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a nsaction after.*
370f0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f * an error is to
37100 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 use this functi
37110 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f on..**.** If ano
37120 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e ther thread chan
37130 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d ges the autocomm
37140 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 it status of the
37150 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
37160 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
37170 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 is routine is ru
37180 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nning, then the
37190 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
371a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f is undefined..*/
371b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
371c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f sqlite3_get_auto
371d0 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 commit(sqlite3*)
371e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
371f0 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 F: Find The Data
37200 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 base Handle Of A
37210 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
37220 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ent.**.** ^The s
37230 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 qlite3_db_handle
37240 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
37250 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 ns the [database
37260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e connection] han
37270 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 dle.** to which
37280 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
37290 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 ement] belongs.
372a0 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 ^The [database
372b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 connection].** r
372c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
372d0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 e3_db_handle is
372e0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 the same [databa
372f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a se connection].*
37300 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 * that was the f
37310 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a irst argument.**
37320 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
37330 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 _prepare_v2()] c
37340 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 all (or its vari
37350 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 ants) that was u
37360 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 sed to.** create
37370 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
37380 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 n the first plac
37390 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
373a0 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 sqlite3 *sqlite
373b0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 3_db_handle(sqli
373c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
373d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 ** CAPI3REF: Ret
373e0 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 urn The Filename
373f0 20 46 6f 72 20 41 20 44 61 74 61 62 61 73 65 20 For A Database
37400 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a Connection.**.**
37410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 ^The sqlite3_db
37420 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 _filename(D,N) i
37430 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
37440 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
37450 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f filename.** asso
37460 63 69 61 74 65 64 20 77 69 74 68 20 64 61 74 61 ciated with data
37470 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 base N of connec
37480 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 tion D. ^The ma
37490 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 in database file
374a0 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65 .** has the name
374b0 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65 "main". If the
374c0 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65 re is no attache
374d0 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 d database N on
374e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
374f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 connection D, or
37500 20 69 66 20 64 61 74 61 62 61 73 65 20 4e 20 69 if database N i
37510 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 s a temporary or
37520 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
37530 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e ase, then.** a N
37540 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
37550 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
37560 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 The filename ret
37570 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 urned by this fu
37580 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 nction is the ou
37590 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 tput of the.** x
375a0 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 FullPathname met
375b0 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d hod of the [VFS]
375c0 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 . ^In other wor
375d0 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ds, the filename
375e0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 .** will be an a
375f0 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 bsolute pathname
37600 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20 66 69 , even if the fi
37610 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 lename used.** t
37620 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 o open the datab
37630 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 ase originally w
37640 61 73 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61 as a URI or rela
37650 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a tive pathname..*
37660 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
37670 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
37680 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c _db_filename(sql
37690 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 ite3 *db, const
376a0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a char *zDbName);.
376b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
376c0 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 Determine if a
376d0 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61 64 database is read
376e0 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 -only.**.** ^The
376f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 sqlite3_db_read
37700 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 only(D,N) interf
37710 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 ace returns 1 if
37720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a the database N.
37730 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e ** of connection
37740 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c D is read-only,
37750 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61 64 0 if it is read
37760 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 /write, or -1 if
37770 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 N is not.** the
37780 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 name of a datab
37790 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f ase on connectio
377a0 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 n D..*/.SQLITE_A
377b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 PI int sqlite3_d
377c0 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 b_readonly(sqlit
377d0 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 e3 *db, const ch
377e0 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f ar *zDbName);../
377f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
37800 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 ind the next pre
37810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a pared statement.
37820 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
37830 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
37840 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e pointer to the n
37850 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 ext [prepared st
37860 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a atement] after.*
37870 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 * pStmt associat
37880 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
37890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
378a0 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d ] pDb. ^If pStm
378b0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 t is NULL.** the
378c0 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 n this interface
378d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
378e0 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 er to the first
378f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37900 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 nt.** associated
37910 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 with the databa
37920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 se connection pD
37930 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 b. ^If no prepa
37940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a red statement.**
37950 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 satisfies the c
37960 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 onditions of thi
37970 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 s routine, it re
37980 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a turns NULL..**.*
37990 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 * The [database
379a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e connection] poin
379b0 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 ter D in a call
379c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e to.** [sqlite3_n
379d0 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d ext_stmt(D,S)] m
379e0 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 ust refer to an
379f0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a open database.**
37a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 connection and
37a10 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 in particular mu
37a20 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c st not be a NULL
37a30 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c pointer..*/.SQL
37a40 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
37a50 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 stmt *sqlite3_ne
37a60 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20 xt_stmt(sqlite3
37a70 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 *pDb, sqlite3_st
37a80 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
37a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
37aa0 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b mit And Rollback
37ab0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 Notification Ca
37ac0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 llbacks.**.** ^T
37ad0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 he sqlite3_commi
37ae0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 t_hook() interfa
37af0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
37b00 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
37b10 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 ion to be invoke
37b20 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 d whenever a tra
37b30 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d nsaction is [COM
37b40 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d MIT | committed]
37b50 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 ..** ^Any callba
37b60 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 ck set by a prev
37b70 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c ious call to sql
37b80 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b ite3_commit_hook
37b90 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 ().** for the sa
37ba0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
37bb0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 ection is overri
37bc0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 dden..** ^The sq
37bd0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
37be0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 ook() interface
37bf0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
37c00 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
37c10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
37c20 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 henever a transa
37c30 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 ction is [ROLLBA
37c40 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b CK | rolled back
37c50 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 ]..** ^Any callb
37c60 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 ack set by a pre
37c70 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 vious call to sq
37c80 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 lite3_rollback_h
37c90 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 ook().** for the
37ca0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
37cb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 onnection is ove
37cc0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 rridden..** ^The
37cd0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69 pArg argument i
37ce0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 s passed through
37cf0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
37d00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c ..** ^If the cal
37d10 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 lback on a commi
37d20 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 t hook function
37d30 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
37d40 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f ,.** then the co
37d50 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65 mmit is converte
37d60 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 d into a rollbac
37d70 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 k..**.** ^The sq
37d80 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f lite3_commit_hoo
37d90 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c k(D,C,P) and sql
37da0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f ite3_rollback_ho
37db0 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 ok(D,C,P) functi
37dc0 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 ons.** return th
37dd0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f e P argument fro
37de0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 m the previous c
37df0 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20 all of the same
37e00 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 function.** on t
37e10 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 he same [databas
37e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c e connection] D,
37e30 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 or NULL for.**
37e40 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66 the first call f
37e50 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e or each function
37e60 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 on D..**.** The
37e70 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c commit and roll
37e80 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 back hook callba
37e90 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65 65 6e cks are not reen
37ea0 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 trant..** The ca
37eb0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 llback implement
37ec0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 ation must not d
37ed0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
37ee0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
37ef0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
37f00 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
37f10 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ked the callback
37f20 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a . Any actions.*
37f30 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 * to modify the
37f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
37f50 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 ion must be defe
37f60 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 rred until after
37f70 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 the.** completi
37f80 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 on of the [sqlit
37f90 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 e3_step()] call
37fa0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 that triggered t
37fb0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 he commit.** or
37fc0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e rollback hook in
37fd0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 the first place
37fe0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 ..** Note that r
37ff0 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 unning any other
38000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c SQL statements,
38010 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 including SELEC
38020 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a T statements,.**
38030 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 or merely calli
38040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
38050 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
38060 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
38070 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
38080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
38090 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
380a0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
380b0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
380c0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 raph..**.** ^Reg
380d0 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 istering a NULL
380e0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 function disable
380f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a s the callback..
38100 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 **.** ^When the
38110 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c commit hook call
38120 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 back routine ret
38130 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b urns zero, the [
38140 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 COMMIT].** opera
38150 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 tion is allowed
38160 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d to continue norm
38170 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 ally. ^If the c
38180 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 ommit hook.** re
38190 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
381a0 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 then the [COMMIT
381b0 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 ] is converted i
381c0 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d nto a [ROLLBACK]
381d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 ..** ^The rollba
381e0 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b ck hook is invok
381f0 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b ed on a rollback
38200 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 that results fr
38210 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 om a commit.** h
38220 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f ook returning no
38230 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 n-zero, just as
38240 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 it would be with
38250 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 any other rollb
38260 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 ack..**.** ^For
38270 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
38280 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e this API, a tran
38290 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 saction is said
382a0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 to have been.**
382b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 rolled back if a
382c0 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c n explicit "ROLL
382d0 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 BACK" statement
382e0 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a is executed, or.
382f0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 ** an error or c
38300 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 onstraint causes
38310 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c an implicit rol
38320 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a lback to occur..
38330 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b ** ^The rollback
38340 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 callback is not
38350 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 invoked if a tr
38360 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 ansaction is.**
38370 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f automatically ro
38380 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 lled back becaus
38390 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 e the database c
383a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f onnection is clo
383b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 sed..**.** See a
383c0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
383d0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 _update_hook()]
383e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 interface..*/.SQ
383f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 LITE_API void *s
38400 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f qlite3_commit_ho
38410 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ok(sqlite3*, int
38420 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 (*)(void*), void
38430 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
38440 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c oid *sqlite3_rol
38450 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 lback_hook(sqlit
38460 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 e3*, void(*)(voi
38470 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f d *), void*);../
38480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
38490 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 ata Change Notif
384a0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b ication Callback
384b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c s.**.** ^The sql
384c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b ite3_update_hook
384d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 () interface reg
384e0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
384f0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 k function.** wi
38500 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 th the [database
38510 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 connection] ide
38520 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 ntified by the f
38530 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a irst argument.**
38540 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 to be invoked w
38550 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 henever a row is
38560 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 updated, insert
38570 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a ed or deleted..*
38580 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 * ^Any callback
38590 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 set by a previou
385a0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 s call to this f
385b0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 unction.** for t
385c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
385d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f connection is o
385e0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a verridden..**.**
385f0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 ^The second arg
38600 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
38610 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 er to the functi
38620 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 on to invoke whe
38630 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 n a.** row is up
38640 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 dated, inserted
38650 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e or deleted..** ^
38660 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
38670 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 nt to the callba
38680 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 ck is a copy of
38690 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 the third argume
386a0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 nt.** to sqlite3
386b0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a _update_hook()..
386c0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 ** ^The second c
386d0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 allback argument
386e0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
386f0 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c TE_INSERT], [SQL
38700 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 ITE_DELETE],.**
38710 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 or [SQLITE_UPDAT
38720 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e E], depending on
38730 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 the operation t
38740 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 hat caused the c
38750 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 allback.** to be
38760 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 invoked..** ^Th
38770 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 e third and four
38780 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 th arguments to
38790 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e the callback con
387a0 74 61 69 6e 20 70 6f